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.
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:
| Variable | Example | What it names |
|---|---|---|
HAMMERKIT_SERVER | hammerkit | The server, as hammerkit remote add registered it. |
HAMMERKIT_REPO | github.com/acme/shop | The repository of the sandbox. |
HAMMERKIT_REF | main | The branch it starts from. |
HAMMERKIT_BUILD | sha256:9f2c… | The published version of the build file. |
HAMMERKIT_TOKEN_COMMAND | gcloud 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.comThe 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.
Agents, workspaces and CI
Share one cache between coding-agent sandboxes, developer workspaces and CI, so work done in one place is never repeated in another.
Server on Kubernetes (GKE)
Run a hammerkit server for coding agents on a GKE cluster with the released image: four steps from an empty cluster to an agent pushing a branch.