A project
A project is a repository with a hakobu.toml at its root. With a server and its MCP added to your agent, ask it to set the repository up for hakobu: its init tool registers the release image on the server and gives the files, which it writes, leaving any that's already there:
hakobu.toml, the project and its server, with an app for the agent to fill in from the repository's Dockerfiles: hakobu builds each app from its own;hakobu.secrets.toml, empty, sealed to the server's key and yours;.github/workflows/hakobu.yml, which builds each push to the default branch and waits for its deploy;.claude/skills/hakobu/SKILL.md, a section inCLAUDE.mdand.claude/settings.json: see Agents.
The release image is ghcr.io/OWNER/REPO, the repository's.
Then
-
The file. Each app gets its
domain, ahealthpath it answers once it's ready (/upby default), and the databases and caches it uses: see hakobu.toml. Thevalidatetool checks it, as CI does. -
Secrets. The server sets the commit's status with a fine-grained token with Commit statuses: Read and write on this repository alone. Make one, and seal it, in your own terminal:
ssh -t nova-1 secret set nova hakobu status_tokenYour agent then adds it to
hakobu.secrets.toml; your app's own secrets go the same way. See Secrets. -
Push. CI builds the apps, pushes them and the release; within 30 seconds the server deploys it, and the job turns green once it's live.
ssh nova-1 statusand the MCP tools show it.The first time, while the job waits, make the release image public: on GitHub, the package
REPO(notREPO-APP), Package settings → Change visibility → Public. Everything in it is sealed to the server's key and yours, and the server polls it with no token; until then,statussays the registry refused. The apps' images stay private: CI seals the job's own token in each release, and the server pulls them with it while the job waits for the deploy. The token dies with the job, so the server keeps none for ghcr.io.A private release works too, with a token for the server to read it: a classic token with
read:packagesalone, given withssh nova-1 server set registry ghcr.io --username YOU(the password typed, hidden). It reads every package of your account, so a public release is the safer one.
An arm64 server
Images are built on CI's runner, for its architecture. For an arm64 server, set runner: ubuntu-24.04-arm in the workflow.
Tests first
The workflow is a job like any other: put your tests in a job of their own and add needs: [test] to the deploy job.
With hakobu on a laptop
hakobu init --server nova-1, in the repository, writes the same files, with an app already for each directory (the root and one level down) that has a Dockerfile, or a stack it recognizes (Node, Python, Go, …), and .mcp.json for hakobu mcp; hakobu secret set hakobu status_token seals the token straight into the file.