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:
| Client | What it gets |
|---|---|
hammerkit remote mcp | MCP tools for any client that speaks MCP: Claude Code, Claude Desktop, Cursor, a custom agent. |
| pi | pi's own read, write, edit, bash, ls, find and grep, working on the sandbox, and check and push. |
| opencode | opencode'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:
tasks:
sh:
image: node:24
mounts: [.]
args: true
cmds: [sh -c]
network: { allow: [registry.npmjs.org] }
timeout: 5mmounts: [.] 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:
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
cdorexportin 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/tmpand/dev/shmare 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 withcd <dir> || exit 1on 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 withnpm testlands 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.runningof 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 owntimeout, withtimed 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. Atimeouton 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:
| Source | What it is |
|---|---|
HAMMERKIT_TOKEN_COMMAND | A 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_TOKEN | Such a token, as the agent's platform hands it over. |
remote add --token-command | The 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:
| Variable | Option | What it names |
|---|---|---|
HAMMERKIT_SERVER | --server | The registered server. Default: the one hammerkit remote use set, else the only registered one. |
HAMMERKIT_SANDBOX | --sandbox | A sandbox of the agent, for example sbx_4vJ0mT2cX9qLw1aB. |
HAMMERKIT_REPO, HAMMERKIT_REF | --repo, --ref | Instead 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 | --build | The 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 | --shell | Its 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:
{
"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:
| Tool | Parameters | What it does |
|---|---|---|
read | path, offset, limit | The lines of a file, numbered like cat -n, in parts for long files. |
write | path, content | Writes a whole file, making its directories. |
edit | path, old_string, new_string, replace_all | Replaces a string that matches exactly once, or every match. |
apply_patch | patch | A *** Begin Patch body or a git diff; every file changes or none. |
search | pattern, path, glob, type, -i, -A, -B, -C, fixed_strings, multiline, output_mode, head_limit | ripgrep on the server. |
glob | pattern, path | The files that match a glob. |
bash | command, 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_task | task, args | Runs 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_logs | run, task, tail, from, limit, grep, ignore_case, context | Reads more of the log of a run. |
changes | format: summary, diff or patch | What changed since the sandbox was fetched. |
check | task | Runs a task as a check on the files a push would commit, see checking before the push. |
push | branch, message | Commits the changes and pushes them to a branch, see taking the work out. |
services_up, endpoint_get, services_stop | see Service runs | Start 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 piThe 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.
{
"dependencies": { "hammerkit": "2.0.0" }
}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 2 | opencode 1 | Parameters |
|---|---|---|
read | read | path (filePath on opencode 1), offset, limit. A directory lists its entries. |
write | write | path (filePath), content |
edit | edit | path (filePath), oldString, newString, replaceAll |
patch | apply_patch | patchText, a *** Begin Patch body or a git diff; every file changes or none. |
shell | bash | command, workdir, timeout in milliseconds. There are no background commands. |
glob | glob | pattern, path, and on opencode 2 limit |
grep | grep | pattern, path, include, and on opencode 2 literal, caseSensitive and limit |
list | path, ignore | |
run_task | run_task | task, args, as the MCP tool, with the same answer |
run_logs | run_logs | run, task, tail, from, limit, grep, ignore_case, context, as the MCP tool |
check | check | task, see Checking before the push |
push | push | branch, 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 filesThe 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:
| Tool | Parameters | What it does |
|---|---|---|
services_up | services, endpoints (service:port, such as web:8080), ttl, sleepTtl, name, branch | Starts 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_get | run, path, service | A 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_stop | run | Takes 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.
Sandboxes
Keep a checkout on the server, run published tasks on it, read, search and edit its files, push its changes to a branch, and the limits that keep sandboxes in check.
Checks
What the server keeps of the tasks a check run passed, the keys they are found by, and the lookup a CI job verifies with.