hammerkit

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.

A sandbox is a caller's own checkout of a repository on the server, which runs work on. It is for an agent without a machine of its own, or a person whose laptop should not build: the files stay on the server between runs, so what npm install, a formatter or a code generator wrote is there for the next run. It is not for production, see Accounts.

The published build file always runs. A sandbox only supplies the files: its own .hammerkit.yaml is just a file, and changing it changes nothing until a new version is proposed and published.

This page covers creating, listing, moving, deleting, running on sandboxes, reading, searching and editing their files, and pushing their changes, on a host and on a Kubernetes backend. Agents covers the clients that let a coding agent work on one.

Who may keep one

The sandboxes of an entitlement list the repositories the caller may keep sandboxes of, one repo (host/path pattern) per entry, and give each branch pattern of it a type:

  • pull: a sandbox may start from a matching branch, and fetch one.
  • push: pull, and pushing to the branch.

Without sandboxes the caller keeps none. It is a list of its own: repos are for runs from a ref only, and a sandbox needs no repos entry for its repository. The entries of all of the caller's entitlements whose repo covers a repository count, and where several patterns match a branch, the higher type wins. An entry's branches never count for another repository. The server has to read the repository too, the same check as for a run from a ref.

server.yaml
entitlements:
  - subject: { iss: https://login.example.com, sub: agent-7 }
    accounts: { op-payments-dev: use }
    repos: [github.com/corp/payments]
    builds: run
    sandboxes:
      - repo: github.com/corp/payments
        branches:
          'agent/**': push     # agent/ and everything below it
          main: pull
      - repo: github.com/corp/*
        branches: { main: pull }

A branch pattern is a branch name, where a segment may hold * (any characters but /) and the last one may be **, everything below.

A sandbox belongs to the caller who created it. For anybody else its id is 404, the same as an id that does not exist, and it does not show in their list.

Creating and managing

CallWhat it does
POST /v1/sandboxes{ "repo": "github.com/corp/payments", "ref": "main" }: fetch a branch into a new sandbox. Answers 201 with the sandbox. A sandbox starts from a branch, never from a tag or a commit, and keeps the commit the branch pointed to.
GET /v1/sandboxesThe caller's sandboxes, oldest first, with their limits and what they used.
GET /v1/sandboxes/<id>One sandbox.
POST /v1/sandboxes/<id>/fetch{ "ref": "next" }: move a sandbox without changes to the commit a branch points to now.
POST /v1/sandboxes/<id>/push{ \"branch\": \"agent/fix-login\", \"message\": \"Fix the login\" }: commit the changes and push them, see Pushing.
DELETE /v1/sandboxes/<id>Cancel the runs on the sandbox, wait for them to stop and remove its files.
{
  "id": "sbx_Jp0dY8m2kQ1aZt5x",
  "repo": "github.com/corp/payments",
  "ref": "main",
  "commit": "4f1c2a...",
  "bytes": 18352211,
  "createdAt": "2026-10-12T21:00:00.000Z",
  "lastUsedAt": "2026-10-12T21:10:00.000Z",
  "busy": true,
  "run": "run_Wm3o0yN2e4cR9pLs"
}

After a push, ref is the branch it pushed to, commit what it pushed, and pushed lists each branch it pushed with the commit it pushed there last.

Creating a sandbox is a fetch, not a run: it runs no task, holds no account and takes no place of the run limits. The server reads the repository with the credential of its sources, as for a run from a ref, and the request waits until the fetch is done. The checkout is shallow, the commit and nothing before it.

A sandbox stays until it is deleted. Nothing expires and nothing is removed on its own, lastUsedAt says when a run or a fetch last used it.

fetch moves a sandbox only while nothing changed its files (files that .gitignore leaves out, such as node_modules, are not changes and stay) and no run holds it, else it is 409. While the caller's sandboxes take their limit of bytes, a fetch is 413, and while all sandboxes take the server's total it is 507. The creates and fetches of one caller run one at a time, so each sees what the one before it added. A fetch that takes the caller over their limit is kept and measured: their next create, edit that adds bytes, or run on a sandbox is refused until they delete one.

StatusWhen
400The body is malformed, the repository is not host/path, the server can not read it, or ref is not a branch of it (a tag or a commit).
403No entry in the sandboxes of the caller's entitlements covers the repository, or none of its branch patterns covers the branch.
404The sandbox does not exist or is somebody else's.
409A fetch of a sandbox with changes, or one a run holds.
413The caller is at their limit of sandboxes or bytes.
502The server could not reach the repository.
507All sandboxes together take what the server allows.

Running on a sandbox

A run names the sandbox as its source, the rest of the request is a normal run:

{
  "definition": "sha256:9f2c...",
  "tasks": ["test"],
  "source": { "type": "sandbox", "id": "sbx_Jp0dY8m2kQ1aZt5x" }
}
  • The published files run on the sandbox. The server reads the published version from a directory of the run, and its tasks work on the sandbox: a build file published as ci/build.yaml works in ci/ of the sandbox. Nothing of the published version is written into the sandbox.
  • One run at a time. A run holds its sandbox from when it is submitted until it is over, waiting for an approval and in the queue included. A second run on the same sandbox waits in the queue for the first, runs on other sandboxes start next to it within the caller's limits (runs.limits.running, 2 by default), on Kubernetes too.
  • What it started from is recorded in the run: the commit the sandbox was fetched at, the git tree of its files when the run was submitted, which together name the changes it held, and whether it held any (clean). The run logs the tree again when it starts, since a run before it on the same sandbox may have changed the files.
  • An approved run works on a copy. A run that waited for an approval runs on a copy of the tree it was approved with, as a check does, not on the sandbox: files .gitignore leaves out (node_modules, outputs) are no part of the tree, an approver does not see them, and they are not in the copy. Its tasks install or build what they need, and what they write stays in the copy. On Kubernetes the copy is uploaded read only, as for a run from a ref: a task writes only into what it generates. The run fails when the sandbox's tree is no longer the approved one; submit it again.
  • No links out. The files are written by tasks and by whoever pushed the commit, so the server does not trust them. A src, mount or output of a task, or one it inherits from a task it depends on, that leaves the sandbox or goes through a symbolic link fails the run, and so does one the server can not look into. It is checked when the run starts and again before each container is made, once it has started (where what the container binds is compared with the sandbox's files, see build files) and before outputs are copied: a task that leaves src -> / behind does not give the next run the server's disk.
  • Containers only. The tasks of a run on a sandbox may only use the runtimes in sandboxes.runtimes, docker by default. A local task would run as the user of the server and could read every other sandbox on the machine, so local has to be listed there by name, and in runtimes.
  • Network. No task or service of a run on a sandbox reaches more than sandboxes.network, none by default: only the services it needs, nor more than runs.network, which holds for every run. A build file can narrow it, never widen it, see network limits.
  • Variables. An env: secret of a run on a sandbox reads only what sandboxes.env.allow lists, nothing by default: the code that would read it is nobody's reviewed code. So does a build file: $NAME or ${NAME} in its envs may read PATH, HOME, CI and what the server sets about the run, else only a variable sandboxes.env.allow lists. A run that reads another is refused with which task reads what.
  • Cache. Runs on sandboxes share a cache per owner, never with runs from a ref: a sandbox holds changes nobody reviewed, and an entry they leave must not reach a reviewed run. An approved run has a cache of its own, apart from the owner's runs that needed no approval.
  • Checks. With "check": true in the source the run works on a copy of the files a push would commit instead of the sandbox, and what it passes counts for a CI job that verifies the pushed commit, see Checks of a sandbox.

What a run wrote stays in the sandbox (not what an approved run or a check wrote, they work on a copy) and counts against the owner's bytes, the docker volumes of its outputs included, whatever permissions a task gave its files. While a caller's sandboxes take more than their limit, their runs on sandboxes are refused with 413.

StatusWhen
400The sandbox does not exist or is somebody else's, or a task reads an env: secret that sandboxes.env.allow does not list.
403No entry in the sandboxes of the caller's entitlements covers the repository and the branch of the sandbox (any more), a check's caller has no repos for the repository, an account of the run does not list sandbox in its source, or the server runs no tasks on sandboxes (only runtimes: [local], see below).
413The caller's sandboxes take more than their limit.

Files

The files of a sandbox are read, searched and edited through the API, in two ways:

  • Typed endpoints for clients without file tools of their own, such as an MCP server: a tree, numbered reads, ripgrep, batches of edits and the changes. Their parameters follow the tools models are trained on: offset/limit reads in cat -n style, exact string replacement with old_string/new_string, git diffs and OpenAI's apply_patch, and ripgrep's options.
  • A raw surface for agent harnesses that bring their own tools and only swap where they run (pi's tool operations, for example): read bytes, write bytes, stat.
CallWhat it does
GET /v1/sandboxes/<id>/treeThe files and directories git sees, see Tree.
GET /v1/sandboxes/<id>/files/<path>A text file as numbered lines, see Reading.
GET /v1/sandboxes/<id>/files/<path>?rawThe bytes of a file, with its sha256 as ETag.
GET /v1/sandboxes/<id>/files/<path>?statWhat a path is: type (file, directory, symlink, or other for a pipe, socket or device), size, exec, modifiedAt, a link's target.
HEAD /v1/sandboxes/<id>/files/<path>The same as headers: content-length, last-modified, x-hammerkit-type, x-hammerkit-exec. 404 when there is nothing.
PUT /v1/sandboxes/<id>/files/<path>Write the body as the file's bytes, creating the directories above it. If-Match: "<sha256>" writes only over that content. 201 for a new file.
POST /v1/sandboxes/<id>/searchripgrep, see Search.
POST /v1/sandboxes/<id>/editsA batch of edits, all or nothing, see Edits.
GET /v1/sandboxes/<id>/changesWhat changed since the commit, see Changes.

Paths are relative to the sandbox, with / between names and no . or ..; in a URL they are percent-encoded (files/src/my%20file.ts). Three rules hold for every endpoint:

  • No symbolic link is followed. A link shows as a link with its target; reading, editing or listing through one is 400. Writing a file where a link is replaces the link. A read checks that the file it opened is the one in the sandbox, so a task that swaps a directory for a link does not lead a read outside of it, and an edit writes into the directories it checked, name by name. A server on Linux needs /proc for that and reads and edits nothing without it (503). Pipes, sockets and devices are 400 too, and a read takes no more than the file held when it was opened.
  • .git/ and credentials stay out. What uploads refuse (.env, .npmrc, keys, .ssh/, .aws/, .git/) is 403 to read or write, and is left out of the tree, the search and the changes, even when the repository commits it. Names match in any case and under the names Windows also opens (.SSH, .git., GIT~1). The git data of a sandbox is not in its files anyway.
  • Runs come first. Reading one file works at any time, also while a run works on the sandbox (not on Kubernetes). Edits, PUT, and the tree, search and changes (which walk the files with git and ripgrep) are 409 while a run holds the sandbox, and the next run waits for a batch of edits to finish.

Every file endpoint needs an entry in the sandboxes of the caller's entitlements that covers the repository and the branch of the sandbox, like a run on it. What edits add counts against the owner's bytes: an edit that would go over is 413.

Tree

GET /v1/sandboxes/<id>/tree?path=src&depth=2 lists what git sees below path (the whole sandbox without it): committed files and new ones, not what .gitignore leaves out, such as node_modules. depth is how many levels, 1 by default; directories show as entries of their own. With glob (**/*.ts, matched against the path below path) it lists the matching files at any depth instead.

{
  "path": "src",
  "entries": [
    { "path": "src/app.ts", "type": "file", "size": 1180 },
    { "path": "src/lib", "type": "directory" },
    { "path": "src/lib/db.ts", "type": "file", "size": 2207 }
  ],
  "total": 3,
  "truncated": false,
  "cursor": null
}

Every list answers its total. A list longer than limit (1,000 by default, at most 10,000) is truncated, and its cursor asks for the next page: ?cursor=<cursor>.

Reading

GET /v1/sandboxes/<id>/files/src/app.ts?offset=40&limit=20 answers lines 40 to 59 of a text file, numbered like cat -n: the line number right aligned in six places, a tab, the line.

{
  "path": "src/app.ts",
  "sha256": "9f2c...",
  "size": 1180,
  "lines": 72,
  "offset": 40,
  "content": "    40\texport function main() {\n    41\t  return run()\n...",
  "truncated": true,
  "nextOffset": 60
}

offset starts at 1, limit is 2,000 lines by default. A read answers at most 256 KiB, and a line longer than 2,000 characters is cut, saying how long it was. truncated and nextOffset say where to read on. A binary file or one that is not UTF-8 is 415: read it with ?raw. A file larger than 32 MiB is 413 for a numbered read; ?raw streams it.

sha256 is what an edit's ifHash and PUT's If-Match compare against, so a change a run made since the read is not overwritten unseen.

POST /v1/sandboxes/<id>/search runs ripgrep on the files, with .gitignore honoured and hidden files searched. The server needs rg on its PATH; without it, search is 501.

{ "pattern": "createUser\\(", "glob": "*.ts", "output_mode": "content", "C": 2 }
FieldWhat it does
patternA regular expression in ripgrep's syntax. Its errors come back as ripgrep says them, with 400.
pathA file or directory to search in, the whole sandbox by default.
globOne glob or a list, as ripgrep's --glob (*.ts, !*.test.ts).
typeA file type of ripgrep (ts, py, rust).
iIgnore case.
fixed_stringsThe pattern is text, not a regular expression.
multilineLet the pattern match across lines (. matches a line feed too).
A, B, CLines after, before and around each match, for content. -i, -A, -B and -C work as names too.
output_modefiles_with_matches (the default): the paths. content: the lines, { path, line, text }, with context: true on the lines around a match. count: the matches per file.
head_limitResults per page, 250 by default, at most 5,000. cursor asks for the next page.

On Linux, a search in a path searches the file or directory the server checked: a link a task swaps in on the way while it runs leads it nowhere else. The .gitignore files of the directories above the path still apply.

Results come in path order. ripgrep stops counting 20,000 results past the page; exact is then false and total is a lower bound. A search that takes longer than a minute is 504.

Edits

POST /v1/sandboxes/<id>/edits applies a batch of operations in order. Each one sees what the ones before it did, and the batch is written only when every operation applies: either all of it changes the files or none of it does. dryRun: true checks the batch and answers what it would change without writing anything.

{
  "ops": [
    { "op": "replace", "path": "src/app.ts", "old_string": "return 1", "new_string": "return 2" },
    { "op": "write", "path": "docs/notes.md", "content": "# Notes\n" },
    { "op": "move", "path": "old.ts", "to": "src/new.ts" },
    { "op": "delete", "path": "tmp/out.log" },
    { "op": "patch", "patch": "*** Begin Patch\n*** Update File: README.md\n@@\n-old\n+new\n*** End Patch\n" }
  ]
}
OperationWhat it does
replaceReplaces old_string with new_string in a text file. old_string has to match exactly once, whitespace included; when it matches more often, the error names the lines. replace_all: true replaces every match.
writeWrites content as the whole file, creating it and the directories above it. encoding: "base64" for bytes.
deleteDeletes a file or a link. Directories are not deleted.
moveMoves a file to to, which may not exist yet.
patchApplies a patch: a unified diff as git diff, git format-patch or diff -u write it, or the body of OpenAI's apply_patch (*** Begin Patch).

replace, write, delete and move take ifHash, the sha256 of a read: when the file holds something else now, the batch is 412. The answer lists what changed:

{
  "dryRun": false,
  "files": [
    { "path": "README.md", "change": "modified", "sha256": "1d0e...", "size": 512 },
    { "path": "old.ts", "change": "deleted" },
    { "path": "src/new.ts", "change": "added", "sha256": "77a1...", "size": 640 }
  ]
}

An operation that does not apply is 422, and the error names it and says what to do: op 0 (replace): old_string is 2 times in src/app.ts, at lines 12, 40: add lines around it until it is there once, or set replace_all, with op (its index) in the body.

How a patch is applied:

  • A git diff applies like git apply: each hunk where its lines are, or at the nearest place where they all are when lines above it moved. It may add, delete, rename and copy files and set the executable bit. Binary patches, links and submodules are refused; write binary files with PUT. A diff of a file with CRLF line endings applies to it either way, and the lines it adds take the file's line ending.
  • An apply_patch body finds each chunk's lines after the one before it, after the line its @@ names: exactly, then ignoring trailing whitespace, then ignoring whitespace around the lines, as OpenAI's reference implementation does. *** End of File ties a chunk to the end of the file, *** Move to: renames.

The patches of one batch compare at most 20 million lines to place their hunks; a hunk that is not in a large file stops there with 422. Give it the line numbers of the file as it is, or more lines around the change. A hunk whose line numbers are past the end of the file is looked for from the end; a line number over a billion is 422.

One batch holds at most 256 MiB in memory, the files it reads and the files it would write together, and processes at most 1 GiB of text (each read, scan and result of its operations counted): a batch over either is 413, send its operations in smaller batches. All batches being planned on the server hold at most 512 MiB together; a batch that would go over is 503, send it again in a moment. A replace whose result would be over 32 MiB is 413 before it is made. While a batch is written, the bytes it adds count against the owner's limit and the server's total, so batches on two sandboxes at once can not pass them together.

Changes

GET /v1/sandboxes/<id>/changes compares the files with the commit the sandbox was fetched at, the way a run sees them: new files count, what .gitignore leaves out does not, and neither does a git repository a task made inside the files. Neither does what hammerkit writes next to a task while it runs: a .hammerkit/ directory at any depth (the last cache entry it resolved, the state of local tasks) is the run's, not a change. The build file .hammerkit.yaml is a change like any other file.

formatWhat it answers
summary (the default){ commit, files: [{ path, status, from, additions, deletions }] }: added, modified, deleted, renamed (with from), lines added and deleted (none for binary files).
diffThe changes as git diff shows them, as text/x-diff.
patchOne commit in git format-patch form, binary files included, for git am on another clone. message, name and email set its message and author (hammerkit by default).

A patch is one way work leaves a sandbox: the caller, or a connector on their side, applies it and pushes a branch. The other is a push by the server. Changes larger than 64 MiB are 413.

StatusWhen
400The path is not inside the sandbox, goes through a link, or is a directory where a file is needed; the body is malformed; a ripgrep error.
403The path is on the deny list; or no entry in the sandboxes of the caller's entitlements covers the repository and the branch of the sandbox any more.
404The sandbox, or the file, does not exist.
409A run holds the sandbox (edits, PUT, tree, search, changes); a move or patch onto a file that exists.
412The file changed since the read that ifHash or If-Match names.
413The edits would take more than the owner's bytes, a file is over 32 MiB, a batch holds more than 256 MiB or processes more than 1 GiB, or the changes are over 64 MiB.
415A numbered read or a text edit of a binary or non-UTF-8 file.
422An operation of the batch does not apply; op names it.
501Search, on a server without ripgrep.
503The batches being planned on the server hold what they may together; send it again in a moment. A read or an edit on a Linux server without /proc.

Pushing

POST /v1/sandboxes/<id>/push commits the changes of a sandbox and pushes the commit to a branch of its repository, with the secret of the server's source for it. The caller's sandboxes decide where to: a sandbox only pushes to a branch whose pattern has the type push in an entry for its repository, agent/** for example, never to a main they may only pull.

{ "branch": "agent/fix-login", "message": "Fix the login\n\nThe session expired a minute early." }
{
  "branch": "agent/fix-login",
  "commit": "9b0e7c...",
  "sandbox": { "id": "sbx_Jp0dY8m2kQ1aZt5x", "ref": "agent/fix-login", "commit": "9b0e7c...", "pushed": { "agent/fix-login": "9b0e7c..." } }
}
  • What is committed is what changes shows: new, changed and deleted files, not what .gitignore leaves out, nothing of the deny list (an .env a task wrote stays on the server) and no .hammerkit/ directory a run wrote. The commit's parent is the commit the sandbox is at.
  • By whom. The commit's author and committer are the caller, as their token names them (name, and email unless the token says it is not verified), else their subject at the host of their issuer (agent-7@login.example.com). A token without name or preferred_username, such as a Google service account's ID token, is named by the part of its verified address before the @ (deploy-bot for deploy-bot@my-project.iam.gserviceaccount.com), and only without one by its subject. A request can not set the author, and a message with Signed-off-by, Reviewed-by, Acked-by or Tested-by is refused: those would attest the commit in somebody else's name. Other trailers, such as Co-authored-by, are the caller's text.
  • Only new branches, or its own. The branch must not exist yet, or be one this sandbox pushed and still at the commit it pushed there. A branch somebody else created or pushed to since is 409: push to a new branch. A sandbox never writes over other work, and it never force-pushes.
  • Afterwards the sandbox is at the pushed commit, on that branch: changes shows what is not pushed yet, and the next push to the same branch adds a commit on top of the last one. A sandbox fetched to another commit since can not push to the branch any more (409), it starts a new one.
  • Like edits, a push waits for a batch of edits, is 409 while a run holds the sandbox, and needs the repository and the sandbox's branch in the caller's sandboxes.

The server reads the branch first with its read credential, then pushes with the write credential, telling the remote which commit it expects the branch at (none for a new one). The remote refuses the push when somebody created or moved the branch in between, and that is 409 too.

StatusWhen
400The body is malformed, the message signs off in somebody's name, or the branch is not a name git takes (no part may start with . or -, or end with . or .lock).
403No push pattern of the caller's entries for the repository covers the branch, the source has no secret, or as for the files, the caller lost the repository or the sandbox's branch.
404The sandbox does not exist or is somebody else's.
409Nothing to push, a run holds the sandbox, or the branch is not this sandbox's to push to.
502The server could not read its push credential (the details are in its log), could not reach the repository, or the remote refused the push for another reason (a rule of the repository, a token without write access, a GitHub App without the workflows permission pushing a workflow file): the error carries the reason the remote gave. Also when the push went through but the sandbox could not be moved to it: the branch stays the sandbox's.

Opening a pull request from the branch is left to the caller: hammerkit holds a token that writes branches, not one that reviews them. A pushed branch runs in the repository's CI like any other, with its secrets unless the operator keeps those branches out, see Sources.

Accounts

A sandbox holds changes nobody reviewed, so its runs only use the accounts whose source lists sandbox. An account without source takes runs from an upload or a ref, not from a sandbox. Keep production accounts on source: [ref].

server.yaml
accounts:
  op-payments-dev:
    providers: { gsm: { env: { CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE: /etc/hammerkit/creds/payments-dev.json } } }
    source: [ref, sandbox]

Config

server.yaml
sandboxes:
  runtimes: [docker]                 # default when runtimes has docker, `local` has to be named (in runtimes too)
  network: { allow: [registry.npmjs.org, '*.githubusercontent.com'] }   # default: none
  env: { allow: [] }                 # default, variables of runs.env env: secrets and envs may read
  capabilities: []                   # default, capabilities of backend.capabilities.allow a task may add
  limits:
    count: 5                         # default, sandboxes per caller
    bytes: 20Gi                      # default, bytes of one caller's sandboxes together
  total: 500Gi                       # default, all sandboxes on the server
KeyWhat it does
runtimesWhat the tasks of a run on a sandbox may run on, out of runtimes. [docker] by default when runtimes has docker. A server with only runtimes: [local] starts as before and refuses runs on sandboxes until local is named here.
networkThe most open network a task or service of such a run gets, written as a task's network: none (the default), open, or { allow: [hosts] } for HTTP(S) to those hosts through the egress proxy. It has to be within runs.network, which caps every run. With local in runtimes it has to be open, hammerkit can not limit a local task.
env.allowThe variables of runs.env.allow or runs.env.set an env: secret, and the envs of a build file, of a run on a sandbox may read. None by default; PATH, HOME, CI and the variables of what the run is from are always readable by envs.
capabilitiesThe capabilities of backend.capabilities.allow a task of a run on a sandbox may add (capAdd). None by default.
limits.countSandboxes one caller may keep. Creating another is 413.
limits.bytesWhat one caller's sandboxes may take together, their git data included. A create that would go over is 413 and leaves nothing behind.
totalWhat all sandboxes on the server may take. Over it, a create is 507.

The bytes of a sandbox are measured after it is fetched and after each run on it. A run's result does not wait for that measure, but the owner's next run or create does. The files are kept below storage (sandboxes/, readable by the user of the server only), with the git data of each sandbox next to its files rather than in them: tasks write to the files, and git on the server never reads a configuration or a hook a task could have written. What a task made unreadable is made readable again before it is measured or deleted, and what a container wrote as another user (a service runs as the user of its image) is given back to the server's user with a short alpine container. A restart keeps the sandboxes, also one whose record can't be read: its files stay for the operator to look at. Changes to sandboxes need a restart.

On Kubernetes

With a Kubernetes backend a sandbox is two PersistentVolumeClaims in its caller's namespace, mounted only while something works on it: an idle sandbox costs its storage and nothing else. The API, the limits and the rules above are the same.

  • Two claims. One holds the sandbox's files, which the tasks of its runs mount. The other holds its git data, which only the pod of its files mounts. A link a task makes in the files leads at most to the root of the files' claim, so no task reaches git's configuration or hooks, as on a host.
  • Fetch. The server fetches the commit with the read credential of sources, as for a run from a ref, and hands the repository to the pod of the sandbox, which takes it into the claim. The credential never reaches the caller's namespace.
  • Files. Reads, searches, edits, the changes and the bytes of a sandbox run in a short pod that mounts its claims, with the same code as on a host (hammerkit server-sandbox), so paths, links and the deny list follow the same rules. The pod has no token and no network (a NetworkPolicy denies all of it), runs on the first pool with no capabilities beyond owning and changing files and a read-only root, and stays while requests come or a run works, backend.sandboxes.idle after the last one.
  • Push. The pod commits the changes; the server copies the objects of the git data, checks that the commit is one on top of the sandbox's without anything of the deny list, and pushes it with the write credential. The write credential never reaches the caller's namespace either.
  • Runs. The process of a run gets a copy of the files to plan with. Its Jobs mount the files' claim itself where their sources are, read and write, so what a task writes is in the sandbox afterwards, as on a host. An approved run and a check work on their copy instead, as a run from a ref does, and never mount the claim: their src and mounts are uploaded and read only, they write into what they generates, and the claims they keep are not the ones the sandbox's other runs keep. A source outside of the sandbox goes into the task's own claim as before. A source or mount that goes through a link is refused, as on a host.
  • Commands. A task of a run on a sandbox that mounts the whole of the sandbox's files (mounts: [.] or src: [.]) and nothing else (no volumes, needed services, secrets or generates), such as the shell task of an agent, runs in the sandbox's runner: one pod next to the pod of the files that stays while that pod does and takes each command over pods/exec. A command then starts in about a second, where a Job takes several seconds to get a pod. Before and after each command, and when a command is cancelled, runs out of time or loses its connection, every process in the runner is killed and /tmp and /dev/shm are emptied, so nothing a command started is left to the next one. The runner has the sandbox's files at /.hammerkit-sandbox, and each command first links the directory of its run (where a Job would have the files) there, so paths are the same as in a Job, and the runner the same from one run to the next. Before each command the runner checks that its mounts are still the mounts it was made with; when a command before moved one, the runner goes and the task fails, so run it again to get a new runner. A task that mounts a part of the files only (src: [src]) runs as a Job: the folders around its mount would be the runner's own, and what a command left there would be in the next runs. What does that is a static busybox (busybox:1.37.0-musl, pinned by digest, which an init container copies in) on a mount the runner can only read, so a command can not replace it, not even as root. Files a command writes elsewhere outside the sandbox, such as the home directory or /usr/local/bin, stay for the next commands while the runner does: the cleanup is for processes, not a fresh filesystem. On a node whose kernel lets a process trace another of its user (kernel.yama.ptrace_scope 0), a command running as root can still attach to the runner's first process, which the cleanup spares, and leave something running that way. Where every command needs a container of its own, set runner: false. The runner has the image, variables, resources, mounts and network of the task: a task that differs in any of them gets a new runner, and the old one goes. A second task of the same run, while the first is in the runner, runs as a Job, and so does a task whose runner the cluster refuses (a full quota) or whose runner does not start (an image without sh). A command stopped while the runner starts (cancelled, or a short timeout) leaves it starting for the next command. With backend.sandboxes.runner: false every task is a Job.
  • Network. Runs on sandboxes get sandboxes.network, none by default, which is a NetworkPolicy on their pods. So with an entitlement that grants sandboxes and a sandboxes.network other than open, the config needs backend.networkPolicy: enforced. Under { allow: [hosts] } a task's egress proxy stays with the sandbox while the pod of its files runs, so the next run of that task on the sandbox uses it instead of waiting for a new one. Each run lets in its own pods only. A task whose allow list or needed services changed gets a new proxy, and the old one goes. All of them go when the pod of the files does. That is one small pod per limited task of an active sandbox, counted by the namespace's quota.
  • One file while a run works, as on a host: the pod of the files stays while the run works.
  • One node. A claim is usually ReadWriteOnce: several pods share it only on one node. The pods that mount a sandbox (the Jobs of its run and the pod of its files) are placed next to each other, so its disk never moves between nodes during a run, which takes seconds each time. The tasks of a run on a sandbox go to the node of the pod of its files, in the first pool; a task on another pool (a local task whose toolImage is on a later pool) fails. When a pod of the run finds no room on that node for 10 seconds, the pod of the files makes way, so the run's pod goes where there is room and the disk follows it.
  • Kubernetes 1.30 or later. The server talks to the pod over pods/exec with the v5.channel.k8s.io protocol, which ends a request's input without closing the connection.
server.yaml
backend:
  type: kubernetes
  sandboxes:
    image: registry.corp/hammerkit@sha256:…  # default: no0dles/hammerkit of the server's version
    size: 4Gi                        # default, what each claim of a sandbox requests
    storageClass: sandboxes          # default: the class of tasks' claims
    idle: 1m                         # default, how long the pod of the files stays
    runner: true                     # default, commands of a sandbox go into one pod that stays
    resources:                       # default, of the pod of the files
      requests: { cpu: 100m, memory: 256Mi }
      limits: { memory: 2Gi }
KeyWhat it does
imageThe image of the pod of a sandbox's files: hammerkit with git and ripgrep, as the published image of the server's version is. It reads and changes every sandbox's files, so pin it by digest.
sizeWhat each of the two claims of a sandbox requests: the most its files, and its git data, can take. No more than sandboxes.limits.bytes.
storageClassThe storage class of sandboxes' claims. When it is one of their own, each caller's namespace gets a ResourceQuota on that class (requests.storage of twice sandboxes.limits.bytes and persistentvolumeclaims of twice sandboxes.limits.count, two claims a sandbox), so the cluster holds the limits too. It can not be the class of tasks' claims, whose claims would count against it.
idleHow long the pod of a sandbox's files stays after the last request. Its runner and egress proxies go with it.
runnerWhether a task that mounts the whole of the sandbox's files, and nothing else, runs in the sandbox's runner instead of a Job of its own.
resourcesThe requests and limits of the pod of a sandbox's files, which runs git and ripgrep over all of them.

The server keeps the record of each sandbox in its storage directory as on a host, and the claims carry the sandbox's id and owner and a label of the server (its namespace prefix and namespace). When the server starts, its own claims without a record are deleted once they are an hour old (younger ones may be a sandbox being created), and a record without claims is dropped. Claims of another server on the cluster, or of this server under another prefix, are left alone, and so are the records of the latter.

On this page