hammerkit
Agents on a server

Agents on a server

Set up a hammerkit server for coding agents and connect pi or opencode to it, so the agent's files and commands stay on the server.

Experimental. The tools and settings can still change between releases.

A coding agent on a hammerkit server works on a sandbox: a checkout of a branch that stays on the server. The agent runs where you start it, on a laptop or in CI, but every file it reads or edits and every command it runs is on the server, in the images, network and accounts of a published build file. When it is done it pushes a branch for review.

These guides set it up end to end, the way it was run to check them:

A server. On Kubernetes (GKE), where every command of an agent is a Job in a namespace of its own, or on one machine.

A build file with a shell task, published to the server (below).

An identity for the agent: a service account of your identity provider with an entitlement that may start sandboxes from main and push to agent/**.

A harness: pi, opencode, or any MCP client with hammerkit remote mcp.

The build file

The agent's commands run as the arguments of a shell task, so the build file decides the image, the network and the accounts of everything the agent runs. Other tasks, such as test, are there for the agent to run as they are.

.hammerkit.yaml
tasks:
  sh:
    image: node:22-alpine
    mounts: [.]
    args: true
    cmds: [sh -c]
    network: { allow: [registry.npmjs.org] }
  test:
    image: node:22-alpine
    src: [src/**, test/**]
    args: true
    cmds: [node --test]

mounts: [.] puts the files of the sandbox into the container, writable, and args: true marks the tasks that take arguments, the agent's commands and a test file: a server with runs.args: declared passes them to no other. The task reads no secrets: a task that does takes no arguments on a server. Publish it with hammerkit remote publish as an identity with builds: publish; it prints the hash of the version. The agent then names the repository, the branch and that hash:

VariableExampleWhat it names
HAMMERKIT_SERVERhammerkitThe server, as hammerkit remote add registered it.
HAMMERKIT_REPOgithub.com/acme/shopThe repository of the sandbox.
HAMMERKIT_REFmainThe branch it starts from.
HAMMERKIT_BUILDsha256:9f2c…The published version of the build file.
HAMMERKIT_TOKEN_COMMANDgcloud auth print-identity-token …Prints a short-lived token of the agent's service account.

A run names exactly the version it runs, so nothing follows a newer one: when the build file changes, publish it again and set the new hash. See Settings for the rest, such as HAMMERKIT_SANDBOX to come back to a sandbox with work in progress.

On the agent's machine

The server is registered per user, in ~/.hammerkit/config.yaml. Register it as the user that starts the agent, with the issuer of the agent's tokens:

npx hammerkit remote add hammerkit https://hammerkit.example.com --issuer https://accounts.google.com

The token command runs again whenever the server stops accepting a token, so a session outlives one token. It is the agent's own identity, never a person's sign-in.

What it is not yet

  • A dev server or another service on the sandbox for the agent to send requests to.
  • Commands that read input, or keep running in the background.

CI on the same server

CI jobs can use the server too, with nothing but their own token: see CI through the server. A job does not even have to wait for the tests when the agent checked them before its push: see Checks that ran before CI.

On this page