Codegen Sandbox

What it is

The codegen sandbox is the hands of a PromptKit codegen agent. The agent (the brain) runs the model and holds context; the sandbox executes everything that touches a filesystem, spawns a process, or makes a network call. They talk over MCP (HTTP+SSE). Prompt injection or model error can corrupt the sandbox; it cannot corrupt the agent runtime or the host.

Tool surface

Filesystem

Read, Write, Edit operate on a single workspace root. Every path is resolved and checked for containment before any I/O. Edit returns post-edit lint findings inline.

Search

Glob (mtime-sorted, gitignore-aware) and Grep (ripgrep-backed) for fast navigation. Structured file:line:rule: message output on lint results.

Shell

Bash foreground + background (via BashOutput / KillShell). Per-call timeouts kill the whole process group; a small denylist catches footguns.

Verification

run_tests, run_lint, run_typecheck use project-type detection (Go today; more languages behind the Detector interface) to run the right command.

Vendor MCP for the web

The sandbox deliberately doesn’t ship WebFetch/WebSearch — wire vendor MCP servers (Brave, Exa, Tavily, official fetch) alongside it instead. See non-sandbox tools.

Safe by default

Path containment, command denylist, secret scrubbing — layered defence-in-depth. The Docker container is the real trust boundary.

How it fits

The codegen sandbox is one provider behind PromptKit’s agent — the piece that actually runs tool calls. PromptKit asks for “a sandbox”; the provider returns an MCP endpoint. The agent then calls tools over MCP; the sandbox executes them inside a container.

flowchart LR
    A["PromptKit agent<br/><i>(brain)</i><br/>runs model<br/>holds context<br/>no exec privs"]
    A -- "MCP (HTTP+SSE)" --> B["Sandbox container<br/><i>(hands)</i>"]
    B --> T1["Read / Edit / Write"]
    B --> T2["Glob / Grep / search_code"]
    B --> T3["Bash (fg + bg)"]
    B --> T4["run_tests / run_lint /<br/>run_typecheck"]
    B --> T5["LSP / AST edits /<br/>render diagrams"]
    B --> V[(workspace volume)]

Defence in depth

flowchart TB
    subgraph Agent["PromptKit agent"]
      direction LR
      M[Model] --- C[Context]
    end
    subgraph Wire["MCP wire"]
      direction LR
      MW[scrubbing middleware]
    end
    subgraph Sandbox["Sandbox container"]
      direction TB
      W[workspace.Resolve<br/>path containment]
      D[Bash denylist]
      S[secrets interface<br/>+ scrub registry]
      W --- D --- S
    end
    Agent -- tool call --> Wire
    Wire -- structured args --> Sandbox
    Sandbox -- structured output --> Wire
    Wire -- scrubbed text --> Agent

Next: Getting Started →