hammerkit

Agents

Let a coding agent work on a sandbox: hammerkit remote mcp for chat clients and agents, and the pi extension and opencode plugin that move the tools of those harnesses onto the server.

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

A coding agent needs to read, edit and search files and to run commands. On a sandbox the files stay on the server and the commands run there, as published tasks in their containers. hammerkit connects agents to it three ways:

ClientWhat it gets
hammerkit remote mcpMCP tools for any client that speaks MCP: Claude Code, Claude Desktop, Cursor, a custom agent.
pipi's own read, write, edit, bash, ls, find and grep, working on the sandbox, and check and push.
opencodeopencode's own read, write, edit, patch, shell, grep and glob (apply_patch, bash and list on opencode 1), working on the sandbox, run_task, check, run_logs and push.

pi and opencode keep the tools their models are tuned for, with the same names, parameters and output: only where they read, write and run moves. The MCP tools take the shapes models are trained on: numbered reads with an offset and limit, an exact string replace, an apply_patch body or a git diff, ripgrep's parameters and a shell command.

The shell task

There is no command endpoint on the server: commands bypassing the published build file would bypass its image, network and accounts. A shell is a published task whose last command is a shell, and every command of the agent is its argument:

.hammerkit.yaml
tasks:
  sh:
    image: node:24
    mounts: [.]
    args: true
    cmds: [sh -c]
    network: { allow: [registry.npmjs.org] }
    timeout: 5m

mounts: [.] puts the files of the sandbox into the container, writable, as the task's working directory. args: true marks it as a task that takes arguments, which a server with runs.args: declared requires. Without it a command in a container runs in an empty directory: the clients then refuse to run it and say the shell task needs mounts: [.]. The timeout stops a command that hangs, such as a test that never ends, before it holds the sandbox for the server's own limit. The clients pass the agent's own timeout of a command too, and the command stops after the shorter of the two.

bash with npm test -- -t login then runs sh -c 'npm test -- -t login' in that image, on the files of the sandbox. Name the task sh or tell the client its name. Use bash -c when the image has bash. A task that reads secrets takes no arguments on a server, so the shell holds no account. Its network is the lower of its own network, runs.network and sandboxes.network.

Named tasks instead of a shell

A shell runs whatever the model types, past the guardrails a repository puts into its named tasks: a test task with --test-timeout=60000 does not help when the model runs node --test itself, and a test that hangs holds the sandbox. run_task runs a published task by its name, with arguments for its last command:

.hammerkit.yaml
tasks:
  test:
    description: run the unit tests, args are test files or --test-name-pattern
    image: node:24
    mounts: [.]
    args: true
    timeout: 10m
    cmds: [npm ci, node --test --test-force-exit --test-timeout=60000]
  lint:
    description: lint the sources
    image: node:24
    mounts: [.]
    args: false
    cmds: [npm ci, npx eslint .]

The description of run_task lists the tasks of the published version, so the model knows what it can run without guessing: each with its description (its last command when it has none) and whether a run of it takes arguments, as the server's runs see it. A task takes none when it says args: false, when it or anything in its run reads a secret or a variable of the server, and under runs.args: declared when it does not say args: true. The server still checks every run. The clients read the list of the version HAMMERKIT_BUILD names when they start, and wait up to 15 seconds for it; without an answer the tools work, and the description says the list is missing.

Set HAMMERKIT_SHELL to an empty value and the build file needs no shell task: hammerkit remote mcp has no bash then, and the opencode plugin no shell (on opencode 1 its bash refuses, see opencode). pi has no run_task yet and its bash refuses without a shell, so keep a shell task for pi.

Leaving the shell out is a setting of the client, which whoever starts the agent picks. To keep agents off a shell, publish a version without a shell task, or with args: false on it: run_task runs every task of the version, a shell task included, and the server runs only what the version has.

What follows from running a command as a task, a shell command or a named one:

  • Commands run one at a time, and only the files are kept between them. A background process ends with its command, and cd or export in one command does not reach the next. On a host each command gets a fresh container. On Kubernetes the commands of a sandbox run in one container that stays, so a command starts in about a second instead of waiting for a pod: before and after each command every process in it is killed and /tmp and /dev/shm are emptied, but what a command writes elsewhere outside the sandbox, such as the home directory, can still be there for the next one. The clients run a command in a directory with cd <dir> || exit 1 on a line before it.
  • The command reads no input and gets none of the agent's variables.
  • While a command runs, the sandbox is held: an edit in the meantime is 409. Agents send tool calls in parallel, so each client takes the calls of its model one at a time, in the order the model made them: an edit sent along with npm test lands before the tests start. A command of another client still holds the sandbox, and an edit then is refused.
  • Agents on sandboxes of their own run their commands side by side, also when they sign in as one identity, up to runs.limits.running of that identity (2 by default); a server for more agents raises it.
  • The timeout an agent gives a command is sent as the run's maxTimeout: the command stops after the shorter of it and the shell task's own timeout, with timed out after <duration>. Each task of the run gets at most this long, so a dependency of the shell task counts on its own. On Kubernetes the first command of a sandbox also waits for its pod to start within that time. A timeout on the shell task bounds the commands that come without one, such as a test that never ends.
  • A command starts in the root of the sandbox. The paths of the agent's machine do not exist there, which the clients tell the model.
  • What it printed comes from the log of the run. A long log is cut at runs.maxLogBytes; the last lines of the task are kept past it.

Sign-in

The clients send the token of the agent, not of a person, to the server registered in the host config (hammerkit remote add), and nowhere else. They look for it in this order:

SourceWhat it is
HAMMERKIT_TOKEN_COMMANDA command that prints a short-lived access token of the agent's own identity, for example a service account or workload identity of the identity provider the server accepts. It runs again when the server stops accepting the token, so a long session outlives one token.
HAMMERKIT_TOKENSuch a token, as the agent's platform hands it over.
remote add --token-commandThe same as HAMMERKIT_TOKEN_COMMAND, registered with one server in the host config, see A token command per server.
hammerkit remote login <server>The sign-in stored on the machine, for an agent a person starts on their own machine.

Give the agent's identity an entitlement with its repositories and branches under sandboxes, builds: run, and no account that holds production secrets. [{ repo: github.com/corp/*, branches: { main: pull, "agent/**": push } }] lets it start from main and push to agent/** with the push tool; with only pull it hands back patches. repos: [github.com/corp/*], with a branch to push to, lets it check its work.

Settings

All three clients take the same settings, hammerkit remote mcp as options too:

VariableOptionWhat it names
HAMMERKIT_SERVER--serverThe registered server. Default: the one hammerkit remote use set, else the only registered one.
HAMMERKIT_SANDBOX--sandboxA sandbox of the agent, for example sbx_4vJ0mT2cX9qLw1aB.
HAMMERKIT_REPO, HAMMERKIT_REF--repo, --refInstead of a sandbox: one of this repository at this branch. When the client starts, it takes a sandbox of yours of the same repository and branch that has no changes and checks it out at the branch again, or creates one. A sandbox stays until it is deleted and the server allows only a few, so set HAMMERKIT_SANDBOX to the id the client prints to come back to work in progress.
HAMMERKIT_BUILD--buildThe hash of the published version of the build file whose tasks run on the sandbox, as hammerkit remote publish printed it. A run names exactly the version it runs: when the build file changes, publish it again and set the new hash.
HAMMERKIT_SHELL--shellIts shell task, sh by default. Empty for none: the clients then leave their shell tool out and run named tasks only.

hammerkit remote mcp

hammerkit remote mcp is an MCP server on stdio for one sandbox. Clients start it as a command:

.mcp.json
{
  "mcpServers": {
    "hammerkit": {
      "command": "npx",
      "args": ["hammerkit", "remote", "mcp", "--server", "corp", "--build", "sha256:9f2c..."],
      "env": { "HAMMERKIT_SANDBOX": "sbx_4vJ0mT2cX9qLw1aB", "HAMMERKIT_TOKEN_COMMAND": "agent-token" }
    }
  }
}

Paths are relative to the root of the sandbox. The tools:

ToolParametersWhat it does
readpath, offset, limitThe lines of a file, numbered like cat -n, in parts for long files.
writepath, contentWrites a whole file, making its directories.
editpath, old_string, new_string, replace_allReplaces a string that matches exactly once, or every match.
apply_patchpatchA *** Begin Patch body or a git diff; every file changes or none.
searchpattern, path, glob, type, -i, -A, -B, -C, fixed_strings, multiline, output_mode, head_limitripgrep on the server.
globpattern, pathThe files that match a glob.
bashcommand, workdir, timeout (seconds)Runs a command as the shell task and answers its output and exit code. A long output keeps its first 50 and last 200 lines, about 30 KB; run_logs reads the rest. Left out without a shell task.
run_tasktask, argsRuns another published task, such as test, and answers its result: status, exit code, why it was not taken from the cache, its last 20 lines. Its description lists the tasks.
run_logsrun, task, tail, from, limit, grep, ignore_case, contextReads more of the log of a run.
changesformat: summary, diff or patchWhat changed since the sandbox was fetched.
checktaskRuns a task as a check on the files a push would commit, see checking before the push.
pushbranch, messageCommits the changes and pushes them to a branch, see taking the work out.
services_up, endpoint_get, services_stopsee Service runsStart services for a person to look at, read a page of one, take them down.

Reads and searches are marked readOnlyHint, the edits destructiveHint, push openWorldHint; bash and run_task keep the defaults, since a command can do anything its task can. The server also tells the client which sandbox, repository and commit the tools work on.

pi

hammerkit is a pi package: installing it adds the extension.

pi install npm:hammerkit
HAMMERKIT_SERVER=corp HAMMERKIT_BUILD=sha256:9f2c... HAMMERKIT_SANDBOX=sbx_4vJ0mT2cX9qLw1aB pi

The extension registers pi's own read, write, edit, bash, ls, find and grep with the sandbox as their backend, the way pi's SSH example does, and runs the user's ! commands there too. pi's working directory stands for the root of the sandbox: a path below it is the same path in the sandbox, anything else is refused. The system prompt names the sandbox, so the model knows nothing is installed on the machine. grep searches with ripgrep on the server. Images are read from the sandbox like any file.

opencode

opencode lets a plugin replace a built-in tool by registering one of the same name. hammerkit's plugin works with opencode 2 and with opencode 1 from 1.18.29. Add hammerkit to the dependencies of the project's opencode directory, install them with npm install in that directory (opencode 2 does not), and re-export the plugin as the default export. Write the server's exact version: a range such as ^1 can install a hammerkit without the plugin.

.opencode/package.json
{
  "dependencies": { "hammerkit": "2.0.0" }
}
.opencode/plugins/hammerkit.ts
export { default } from 'hammerkit/harness/opencode'

opencode 1 also needs "@opencode-ai/plugin": "*" in these dependencies, which it adds itself when it starts. Its plugin files that re-export HammerkitPlugin still work there; opencode 2 loads only the default export.

Then start opencode with the settings as variables, as the user whose host config has the server (hammerkit remote add). opencode 2 runs a background service that keeps the variables it was started with: run opencode service stop after changing them, or opencode run --standalone to start with the current ones.

opencode 2opencode 1Parameters
readreadpath (filePath on opencode 1), offset, limit. A directory lists its entries.
writewritepath (filePath), content
editeditpath (filePath), oldString, newString, replaceAll
patchapply_patchpatchText, a *** Begin Patch body or a git diff; every file changes or none.
shellbashcommand, workdir, timeout in milliseconds. There are no background commands.
globglobpattern, path, and on opencode 2 limit
grepgreppattern, path, include, and on opencode 2 literal, caseSensitive and limit
listpath, ignore
run_taskrun_tasktask, args, as the MCP tool, with the same answer
run_logsrun_logsrun, task, tail, from, limit, grep, ignore_case, context, as the MCP tool
checkchecktask, see Checking before the push
pushpushbranch, message, see Taking the work out

The tools answer in opencode's words, and opencode still picks the patch tool for GPT models and edit and write for the others. Paths are relative to opencode's directory or absolute below it, which stands for the root of the sandbox. A long shell output keeps its first and last lines, like the MCP tool, and names the run_logs call that reads the rest. run_task and run_logs take their turn with the other tools, in the order the model made the calls. On opencode 2 the plugin also removes the worktree tools, which would make worktrees on the machine opencode runs on.

With an empty HAMMERKIT_SHELL the plugin removes opencode 2's shell. opencode 1 has no way to remove a tool, so its bash stays and refuses: its own would run on this machine. Turn it off with "tools": { "bash": false } in the opencode.json of opencode 1 so the model does not try it.

opencode carries on without a plugin that fails to load, and without a word: its own tools then work on the machine opencode runs on. On opencode 1 hammerkit's plugin keeps that from happening when it can. It takes the @opencode-ai/plugin of the opencode directory when hammerkit is linked there (npm install ../hammerkit, file:) and does not see it, and when it finds none at all, its tools still replace opencode's and refuse with what is missing. A plugin file that does not load at all cannot do that: hammerkit not installed, or on opencode 2 a file without the default export. Check once that the tools are hammerkit's, in a directory with nothing but the opencode setup. The answer names the files of the sandbox, not the ones of your directory:

opencode run --standalone 'List the files of the project root with the read tool.'

On opencode 1, leave out --standalone, or list them without a model: opencode debug agent build --tool list.

Tools the plugin does not replace still work on the machine opencode runs on, such as webfetch and skill. Turn off the ones that touch local files and that your opencode version still has, for example "tools": { "multiedit": false } in the opencode.json of opencode 1.

Checking before the push

Every client has a check tool with a task, such as test. It runs the task as a check: on a copy of the files a push of the sandbox would commit, not on the sandbox, whose ignored files the agent can write. When it passes, a CI job that runs remote verify for the pushed commit passes without running the task, see Checks that ran before CI. The tool answers whether it passed, and the last lines of a failure:

check test passed (run run_Qx3k9ZpL2mW7vN4a): CI can verify it for a push of these files

The tool tells the model to check right before push and to push without changing files in between. A check needs repos for the sandbox's repository in the agent's entitlement, as a run from a ref does.

Taking the work out

Every client has a push tool with a branch and a commit message. The server commits the changes of the sandbox as the agent's identity and pushes them with the source's own credentials, only to a branch the entitlement gives push, such as agent/**; any other branch is refused with what the agent may push to. The sandbox is at the pushed commit afterwards, so the next push carries only new work. Without a branch to push to, the MCP tool changes with format: patch gives a patch to apply with git am.

Service runs

Every client has three tools for service runs, to bring the app up for a person to check the change, or to try it out itself:

ToolParametersWhat it does
services_upservices, endpoints (service:port, such as web:8080), ttl, sleepTtl, name, branchStarts the services of the published build file with the files of the sandbox, or of a pushed branch of its repository, and answers once they are up: the address of each endpoint and until when they stay. The same name again replaces the run and keeps its addresses.
endpoint_getrun, path, serviceA GET of a path of an endpoint of the run, signed in as the agent: its status and the first 20000 characters of the body (at most 256 KiB of it is read, the rest is not downloaded). Only at the addresses the server gave the run, so the token goes nowhere else.
services_stoprunTakes the services down.

The agent's identity needs an endpoints level publish for the repository to name endpoints, and the people who look need open, see Who opens an endpoint. On a Kubernetes backend a service run starts from a branch only: push first, then services_up with that branch.

What is not covered yet

  • Commands that read input, and long-running background commands.

On this page