hammerkit
Agents on a server

pi on a sandbox

Step by step: set up the pi coding agent for an existing project so that it reads, edits and runs everything on a sandbox of a hammerkit server, and hands its work back as a branch.

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

At the end of this tutorial you start pi on your machine, give it a task for your project, and it works on a copy of your repository on a hammerkit server. Your own checkout stays untouched: pi never reads or writes a file on your machine and never runs a command there. When it is done, its work shows up as a branch in your repository, ready for a pull request.

This page was run as written with pi 1.2.0 against the server of Server on Kubernetes.

How it fits together

Four pieces work together. You set up the last three in this tutorial.

  • The server keeps a sandbox for the agent: a checkout of your repository at a branch, for example main. Every file pi reads or edits is a file of the sandbox.
  • Your build file has a shell task. Every command pi runs, such as npm test, is handed to that task as its argument and runs on the server, in the task's image. The build file is published to the server once; the server answers with a hash that names exactly that version.
  • The agent's identity is a service account, not you. pi signs in to the server as that account, and the server only lets it start sandboxes from main and push to agent/… branches.
  • pi runs on your machine and talks to the language model as usual. hammerkit's pi extension swaps pi's tools (read, write, edit, bash, ls, find, grep) for ones that work on the sandbox, and adds a push tool.

Before you start

A hammerkit server for your GitHub repository. Server on Kubernetes sets one up on GKE: the server checks out and pushes to your repository with a GitHub App, and accepts Google sign-ins. If someone else runs the server, ask them for its address and the issuer of the tokens it accepts, for example https://accounts.google.com.

Service accounts for the agent and the publisher, and the right to act as them. Service accounts on Google Cloud creates hammerkit-agent and hammerkit-publisher, gives you the role that lets gcloud print their tokens, and shows the entitlements the server needs for them. The Kubernetes guide does this in its step 1; with a server someone else runs, have them add you as in Let your team act as them.

Node.js 24 or later on your machine, for pi and the hammerkit CLI.

An API key of a model provider that pi supports. The examples use OpenRouter.

The examples below use the repository github.com/acme/shop, a server registered as hammerkit, and Google service accounts. Replace them with yours.

1. Install the hammerkit CLI

npm install -g hammerkit@2.0.0    # the server's version
hammerkit --version

hammerkit --version has to print the server's version. hammerkit needs Node.js 24: on an older one npm warns EBADENGINE, and with a range instead of an exact version it quietly installs an old hammerkit without the agent clients.

Use the same version as the server. The CLI registers the server in step 2 and publishes the build file in step 3; pi's extension in step 4 comes from the same package.

2. Register the server on your machine

The CLI keeps a list of servers for your user, in its config file. Add the server under a short name of your choice, with the issuer of the tokens it accepts:

hammerkit remote add hammerkit http://127.0.0.1:8480 --issuer https://accounts.google.com

hammerkit is the name you use from now on. The address here is the kubectl port-forward of the Kubernetes guide, which has to keep running while pi works. Plain http is only accepted for 127.0.0.1 and localhost; a server on any other address needs https.

Register it as the same user that starts pi later: pi's extension reads this list.

3. Add a shell task to your project and publish it

Open your project's .hammerkit.yaml, or create one in the root of the repository, and add a task for the agent's commands. For a Node.js project:

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

Line by line:

  • sh is the task's name. The extension looks for a task called sh unless you set HAMMERKIT_SHELL.
  • image is the container every command of the agent runs in. Pick one with the tools your project needs: the agent can only run npm, go or python if the image has them.
  • mounts: [.] puts the files of the sandbox into the container, writable. Without it, the commands would run in an empty directory.
  • args: true says the task takes arguments. A server can be set to pass arguments to such tasks only, so mark the shell task even where nothing requires it.
  • cmds: [sh -c] is the trick: the agent's command is appended to the last command as one argument, so npm test runs as sh -c 'npm test'.
  • network lists what the commands may reach. The sandbox is a fresh checkout without node_modules, so the agent installs dependencies itself and needs the registry. The server can narrow this further, never widen it.

Leave secrets out of this task: a task that reads a secret takes no arguments on a server. Your other tasks, such as test or lint, stay as they are, and pi can run them too.

If you have Docker, try the task on your machine before you publish it:

hammerkit run sh -- 'ls && node --version'

Commit the file and get it onto main: the agent's commands run in the published version, and its sandbox is a checkout of main, so the two should not drift apart. Then publish it from the root of your checkout, signed in as the publisher's service account:

HAMMERKIT_TOKEN_COMMAND="gcloud auth print-identity-token --audiences=hammerkit --include-email \
  --impersonate-service-account=hammerkit-publisher@my-project.iam.gserviceaccount.com" \
  hammerkit remote publish hammerkit
published to hammerkit: sha256:9f2c61d0… (1 file)

If this exact version was published before, it prints already published to hammerkit: with the same hash instead; that is fine.

HAMMERKIT_TOKEN_COMMAND makes this one command sign in as hammerkit-publisher: gcloud prints a token of that service account for you. That only works once you may act as it, see Service accounts on Google Cloud. Write your project instead of my-project; with the Kubernetes guide, the account is $PUBLISHER of its step 1.

Copy the hash, sha256: and 64 hex digits: it names this version of the build file, and pi uses it in step 5. The server never takes task definitions from the agent itself, so the agent can not change what its commands run in. When you change the build file later, publish it again and use the new hash; an agent that is already running keeps the old one.

4. Install pi and the extension

npm install -g @earendil-works/pi-coding-agent
pi install npm:hammerkit@2.0.0    # the server's version
pi list

pi install adds hammerkit as a pi package for every pi session of your user. pi list shows it under the user packages.

5. Tell the extension where to work

The extension reads its settings from environment variables. Put them in a file, so every session starts the same way:

agent.env
export HAMMERKIT_SERVER=hammerkit                   # the name from step 2
export HAMMERKIT_REPO=github.com/acme/shop          # the repository of the sandbox
export HAMMERKIT_REF=main                           # the branch the sandbox starts from
export HAMMERKIT_BUILD=sha256:9f2c61d0…             # the hash from step 3
export HAMMERKIT_TOKEN_COMMAND="gcloud auth print-identity-token --audiences=hammerkit --include-email \
  --impersonate-service-account=hammerkit-agent@my-project.iam.gserviceaccount.com"
export OPENROUTER_API_KEY=…                         # for the model, not for hammerkit

HAMMERKIT_TOKEN_COMMAND is how pi signs in as the agent: a command that prints a short-lived token of the agent's service account. The extension runs it again whenever the server stops accepting the token, so a long session needs no new sign-in. The command above works once you may act as hammerkit-agent (with the Kubernetes guide, $AGENT of its step 1), see Service accounts on Google Cloud; check it there with a token test. With another identity provider, use any command that prints a token of the agent's account.

6. Start pi and check where it works

Start pi in a new, empty directory. pi treats its working directory as the root of the sandbox, so this directory only stands in for it: nothing in it is read or changed.

mkdir shop-agent && cd shop-agent
source ../agent.env
pi --provider openrouter --model anthropic/claude-haiku-5.5

Ask pi first: "List the files of the project." The answer has to show your repository's files, not an empty directory. On this first tool call the extension signs in, takes a sandbox of the agent at main that has no changes (or creates one) and shows its id, for example sbx_4vJ0mT2cX9qLw1aB. Every tool works on that sandbox from then on.

A sandbox stays on the server until it is deleted, with whatever pi changed in it. To come back to unfinished work in a later session, add export HAMMERKIT_SANDBOX=<id> to agent.env; without it, pi starts from a clean checkout of main again.

7. Give it work and get it back

Give pi a task the way you would in your own checkout, and tell it where to push, for example:

The cart total skips the last item. Fix it, run the tests and push the fix to agent/fix-cart.

pi edits the files of the sandbox, runs npm ci and npm test as the shell task on the server, and finally calls push. The server commits the changes as the agent and pushes them with its own GitHub credentials. Only branches the entitlement allows are accepted, here agent/…; for any other branch, pi is told which ones it may push to.

The branch now shows up in your repository. Open a pull request from it and review it like any other.

Without a terminal

-p runs one prompt and exits, for example in CI. pi waits for input on stdin, so close it when nothing feeds it:

BRANCH=agent/fix-cart-$(date +%Y%m%d%H%M%S)    # a new branch for every run
pi --provider openrouter --model anthropic/claude-haiku-5.5 --no-session \
  -p "The cart total skips the last item. Fix it, run the tests and push to $BRANCH." < /dev/null
git -C "$CHECKOUT" ls-remote --exit-code origin "refs/heads/$BRANCH"

pi can end without pushing, for example when its tools failed, so the last line fails the job when the branch is not there. $CHECKOUT is a checkout of the repository that may read it, for example the CI job's own; a branch name of its own for every run keeps an earlier run's branch from passing the check.

--mode json prints every tool call and result as a line of JSON.

When it does not work

What you seeWhat it means
pi lists an empty directory, or files of your machineThe extension is not loaded: check pi list.
server hammerkit is not registeredStep 2 was run as another user, or HAMMERKIT_SERVER names another server.
… is not the hash of a published versionHAMMERKIT_BUILD holds a name or a shortened hash. Use the full hash that step 3 printed.
unable to reach http://…: fetch failed: connect ECONNREFUSED …Nothing listens at the server's address, for example kubectl port-forward has stopped.
unable to reach https://…: fetch failed: …, this machine does not trust the certificate of the serverThe server's certificate comes from a company or private CA: name that CA's file in NODE_EXTRA_CA_CERTS, which takes one file.
error: lost connection to pod, Unable to connect, or an empty reply from the serverkubectl port-forward ended, because the server's pod was replaced or the connection dropped: start it again, or run it in the loop of the Kubernetes guide.
could not read the source credential …The server can not mint its token for the repository; the rest of the message says why. See the check after the deploy.
Permission 'iam.serviceAccounts.getAccessToken' deniedYou may not act as the service account in HAMMERKIT_TOKEN_COMMAND yet, see Service accounts on Google Cloud.
you are not entitled to keep sandboxes on this serverThe token is not the agent's, or its entitlement has no sandboxes: check the account in HAMMERKIT_TOKEN_COMMAND.
The shell task needs mounts: [.]The shell task does not mount the sandbox: add mounts: [.] (step 3), publish again and set the new hash.
npm: not found, or a download that times outThe shell task's image lacks the tool, or its network does not allow the host. Change the task, publish again and set the new hash.

See Agents for what the extension does with each of pi's tools.

On this page