hakobuDocs
Menu

A project

View as Markdown

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 in CLAUDE.md and .claude/settings.json: see Agents.

The release image is ghcr.io/OWNER/REPO, the repository's.

Then

  1. The file. Each app gets its domain, a health path it answers once it's ready (/up by default), and the databases and caches it uses: see hakobu.toml. The validate tool checks it, as CI does.

  2. 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_token
    

    Your agent then adds it to hakobu.secrets.toml; your app's own secrets go the same way. See Secrets.

  3. 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 status and the MCP tools show it.

    The first time, while the job waits, make the release image public: on GitHub, the package REPO (not REPO-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, status says 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:packages alone, given with ssh 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.