Sandboxed workers

A repository's sandbox setting runs its workers in a container. This page lists the keys of that setting and what reaches the container from the host. The other pages in this section cover each part in turn.

repos:
  - path: /home/you/code/my-service
    sandbox:
      kind: docker
      image: ghcr.io/acme/agent@sha256:...
      resources: {cpu: 2, memory: 4g, pids: 512}
      network:
        install: {allow: [registry.npmjs.org]}
        runtime: {allow: [api.github.com]}

The sandbox key

The keys depend on kind. A key a kind refuses stops repos.yaml from loading, naming the entry.

Set the key in repos.yaml or in policy.sandbox, not both. It is part of the repository policy layer: once it is set, no chain, node or task can turn it off or change it, limits and network policy included, and sandbox: false on a repo cannot turn off one a layer set.

What reaches the container

A sandboxed task runs docker run --init (or podman run) with every capability dropped, within its resource limits. It runs as a user that leaves what it writes yours, on rootless Docker and Podman too.

sandbox.yaml says which CLI runs it, and what happens on an SELinux-enforcing host. Only what is listed here reaches the container:

Home, results and git identity

• HOME. $KRAFT_HOME/run/sandbox-home/<work item>, read-write and kept across sessions, so an agent CLI keeps its state and can resume a paused session. A CLI config directory Kraft owns (Cursor's) lives there too, one per item.
• Results. From $KRAFT_HOME/run/results, only this work item's own files: its sessions' result files, review packages and long instructions, read-only, and the session's own result file, read-write. Nothing of another item's is mounted.
• Git identity. GIT_AUTHOR_* and GIT_COMMITTER_* from the server's environment, else your user.name and user.email for the repository. Repository hooks never run in the container, as they never run on a worker's commits outside one.

Abandoning or archiving an item removes its ref store and sandbox home.

Forwarded credentials

The container's own environment still holds the values, so docker inspect shows them to anyone who can reach the container runtime. A name listed under credentials is the exception: the container holds only its sentinel, and docker inspect shows that. Logins kept in your home directory or the OS keychain do not reach a sandbox.

Tool policy

• Amp's and OpenCode's rules travel with the launch, and Amp's rules file is mounted read-only.
• Which harness's tool policy is accepted or refused, with and without a network policy, is told in Callbacks from a sandbox.
• Codex runs with sandbox_mode=danger-full-access unless a task or harness profile sets a mode other than workspace-write, because its own sandbox cannot start inside Docker.

The image

It must hold the agent CLI (and, for a fallback, every harness it may fall back to) on its PATH, plus git, sh and CA certificates, and curl under a network policy (the kraft shim uses it).

Before a task's first launch in an image, Kraft asks the image, through its own entrypoint and with the repository's env, whether the command is there. An image that answers no stops the item as a configuration error before anything runs.

kraft admin doctor checks:

• that the runtime answers
• that SELinux has an answer in sandbox.yaml where it enforces
• that an extra CA can be read
• that the image is pulled

Pull it before filing work, or the first launch pulls it inside the task's time cap.

Limits

• With unrestricted_network: true and no network policy, the container has the default bridge network: open egress, and on a cloud VM the metadata address is reachable.
• A worker can still delete objects from your repository, which breaks it loudly but cannot put content on another branch.
• Without a network policy a worker has no channel to Kraft, and its network is not restricted, so Kraft refuses the launch unless unrestricted_network: true is set: see Callbacks from a sandbox.
• Only repositories keeping refs in git's default files storage are supported; a reftable repository stops the item.

In this section

• Resource limits: the CPU, memory and process limits of a container, and what happens when a memory limit kills a process.
• Callbacks from a sandbox: how a sandboxed worker reaches Kraft, and what is refused without a network policy.
• Network policy: which hosts a sandboxed task may reach.
• Credentials: secrets the container never holds.
• Kits: a sandbox that an image's own descriptor declares.
• sandbox.yaml: the host-wide file for the container CLI, SELinux, an extra CA and the proxy.
• Git in a sandbox: the copy of the repository's refs, a workspace's members, and what Kraft's own git does in the worktree.