hakobuDocs
Menu

Secrets

View as Markdown

An app's secrets live in its repository, in hakobu.secrets.toml next to hakobu.toml, each value sealed on its own with age to two keys: the server's and yours. Anyone with the repository can add or replace a secret, an agent too; only the server and you can read one. The file is committed like any other, and its diffs show which secret changed, never a value.

Adding one

You type the value, in your own terminal; the server seals it, and your agent puts it in the file:

ssh -t nova-1 secret set nova web STRIPE_KEY    # PROJECT APP NAME; typed, hidden

The server keeps the sealed value for 7 days. The agent's MCP tool pending_secrets gives it, as STRIPE_KEY = "age:…" for [apps.web]; the agent writes it into hakobu.secrets.toml (replacing the one there), pushes, and clears it. The value never goes through the agent, nor its chat: it sees only what's sealed, which it can't open. From a password manager, without typing:

op read op://crm/stripe/key | ssh nova-1 secret set nova web STRIPE_KEY

The names are in the file; to remove one, the agent deletes its line. An app gets its secrets as variables. A secret can't have the name of one the file already sets (in env, from uses, PORT or HAKOBU_REVISION): the server refuses that release rather than guess which wins.

hakobu's own

APP hakobu is for hakobu itself. status_token is the GitHub token that sets the commit's hakobu/deploy status: a fine-grained token with Commit statuses: Read and write on the repository alone. A release from a GitHub repository without it is refused, so a deploy is never silent.

How they reach the server

CI puts the file, still sealed, in the release image; the server opens it with its key as it deploys. Each value is sealed for its place, project, app and name: one key opens every project's on the server, so a value pasted into another project's file, or under another app or name, isn't opened there, and that release is refused. A rollback takes the older image but today's secrets, so a rotated key stays rotated.

Database and cache passwords aren't secrets you keep: the server makes them.

Values sealed by hakobu before 1.6 have no place. The server still opens those its releases deployed before, where they were; any other is refused, and secret set seals it again with its place.

A new server

A new server has a new key, which can't open what was sealed to the old one. Put the old server's key back from your copy of /var/lib/hakobu/key.age, or start the file anew for the new server and set each secret again (the file names them).

With hakobu on a laptop

hakobu secret init               # start the file, sealed to the server's key and yours
hakobu secret set web STRIPE_KEY # read from stdin (or typed, hidden): never an argument
hakobu secret list               # names only
hakobu secret unset web STRIPE_KEY

These seal straight into the file, with no server: secret init asks it for its public key once.