Skip to content

Sandboxes behind one interface: the agent outside them, a container per run, and the site on Windows - #21

Merged
WaylandYang merged 3 commits into
devfrom
feat/sandbox-provider
Oct 18, 2026
Merged

WaylandYang merged 3 commits into
devfrom
feat/sandbox-provider

Conversation

@WaylandYang

Copy link
Copy Markdown
Contributor

Where a run's workspace lives and where its commands run now sits behind one interface, SandboxProvider (app/server/sandbox.ts). This PR adds two backends for it, moves the coding agent out of the sandbox, and makes the site run natively on Windows.

The seam

  • SandboxProvider: create, exec (streams output, takes an abort signal and a timeout), readFile, writeFile, mkdir, stat, list, copy, delete, destroy, an optional snapshot, plus python and workspacePath. Paths are always relative to the workspace root.
  • LocalProvider (sandbox-local.ts, the default) is the per-run uid + prlimit / macOS sandbox-exec code moved out of harness.ts without changing what it does. Two holes found during the move are closed. A write that follows a dangling link would create its target outside the workspace, as root in the runner's container. A write through a link into TASK.md, bin/, docs/ or data/ used to succeed.
  • harness.ts keeps the rules: read-only entries, size limits, one terminal command at a time. It does its file, terminal, SQLite-viewer and run-deletion work through the provider. These file functions are now async.

pi runs outside the sandbox

  • pi runs as the runner, in its own agent/ folder, not as the run's user inside the workspace. The relay token is no longer readable by that user. pi does not start in the workspace, because it would read a .pi/ settings folder there.
  • A per-turn extension (tools.js, replacing guard.js) registers pi's own read, write, edit and bash, with operations that call back to the runner over pi's IPC channel. The runner carries them out through the provider, and the customer's material stays read-only. Commands pi still has running are aborted when pi exits. The bin/ask and bin/pilot guard is merged into the same extension. The agent's turn followed as it happens: thinking, timed steps, and a stream a page picks up again #17's thinking settings, step events and edit diffs are unchanged.

A container per run (FDEGYM_SANDBOX=docker)

  • DockerProvider (sandbox-docker.ts) keeps files on the server's disk and runs commands with docker exec in one container per run:
    • the workspace is bound at /workspace, and the read-only entries are bound again on top, read-only;
    • an unprivileged user, --cap-drop ALL, no-new-privileges;
    • per-run memory, CPU and process limits.
  • The container has no network. A small Python relay inside it, talked to over docker exec's stdin/stdout, forwards only that run's NPC, LLM-gateway and service ports to the server's 127.0.0.1. Docker Desktop's --internal networks cannot reach the host, hence the relay.
  • Stopping or timing out a command kills its whole process group inside the container.
  • After Docker or the server restarts, the next command starts the container again, or recreates it if it is gone.

Windows

  • The site runs natively with FDEGYM_SANDBOX=docker:
    • pi is stopped with child.kill (Windows has no process groups);
    • run.py serve is stopped with taskkill /T;
    • Git for Windows' diff is used for the Changes tab when diff is not on the PATH (FDEGYM_DIFF overrides);
    • spawned processes no longer open console windows.
  • pnpm dev no longer sets API_PORT inline, which cmd.exe cannot do. Under pnpm dev the server itself keeps the API on 8787.
  • engines.node >= 22.12: on older Node, pnpm skips Vite 8's native binding and the build fails.
  • The runner and admin pages show a new isolation label, "one container per run".

Docs

  • docs/sandbox.md covers the interface, both backends, how pi reaches the workspace, and a design for a CubeSandbox backend:
    • one template snapshot per case version, cloned per run;
    • egress through a per-run gateway;
    • grading in a fresh clone;
    • host requirements.
  • docs/self-hosting.md adds a Windows section and the new settings.

Not covered yet

  • A trial day and grading still run the delivered system on the server's machine, as before. The CubeSandbox design moves them into a clone.
  • run.py new/serve/grade has not been exercised with a real case on native Windows.

Tests

  • New sandbox.test.ts (LocalProvider), skipped on Windows.
  • New sandbox-docker.test.ts, skipped without Docker. It covers the no-network relay, read-only mounts, killing a whole process tree, long command lines, and recreating a container that went away.
  • New pi tests that show the tools go through the provider and cannot reach outside the workspace or change TASK.md.
  • Linux (node:22 + postgres:16, local backend): typecheck, build, 49 passed, 6 skipped (no Docker there).
  • Windows 11 + Docker Desktop 4.39, FDEGYM_SANDBOX=docker, Node 23: 48 passed, 7 skipped (the LocalProvider tests). This includes pi, the agent and the database-backed tests.

🤖 Generated with Claude Code

WaylandYang and others added 3 commits October 18, 2026 11:37
- server/sandbox.ts: the SandboxProvider interface (create, exec with
  streaming/abort/timeout, readFile, writeFile, mkdir, stat, list, copy,
  delete, snapshot?, destroy). Paths are workspace-relative.
- server/sandbox-local.ts: LocalProvider, the per-run uid + prlimit /
  macOS sandbox-exec logic moved out of harness.ts unchanged. Its own
  writes now also refuse a dangling link (which would create its target
  as root) and writes into the read-only entries through a link.
- harness.ts: the file API, terminal, SQLite viewer, taskOf and deleteRun
  go through the provider; policy (KEPT, size limits, one command at a
  time) stays here. File functions are now async.
- pi.ts: pi runs as the runner, in its own agent/ folder, not as the
  run's user in the workspace, so the relay token is out of the run
  user's reach. A per-turn extension (tools.js, replacing guard.js)
  registers pi's read/write/edit/bash with operations that call back to
  the runner over pi's IPC channel; the runner does them through the
  provider and keeps the customer's material read-only. pi's commands
  are aborted when it exits. The bin/ask|pilot guard is merged in.
- Tests: sandbox.test.ts for LocalProvider; pi tests that the tools go
  through the provider and cannot reach outside the workspace or
  change TASK.md.
- docs/sandbox.md: the seam, the agent bridge, and a CubeSandbox design
  (templates per case version, clone per run, egress via a run gateway,
  grading in a fresh clone, host requirements).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- server/sandbox-docker.ts: DockerProvider (FDEGYM_SANDBOX=docker). Files
  stay on the server's disk (LocalProvider's file ops); commands run in a
  container per run via docker exec: workspace bound at /workspace, the
  read-only entries bound again read-only, unprivileged user, cap-drop
  ALL, no-new-privileges, per-run memory/CPU/pids limits, --network none.
  A Python relay in the container, spoken to over docker exec stdio,
  forwards only the run's own NPC/LLM-gateway/service ports to the
  server's 127.0.0.1. Commands run under setsid and are ended with
  os.killpg in the container (dash's kill cannot take a group); shell
  lines go in on stdin (Windows command-line limit). Containers are
  started or remade lazily after a restart.
- SandboxProvider gains `python` and `workspacePath(id)`; pi tells the
  model the sandbox's path (/workspace under Docker) and replaces its own
  folder in the prompt in either slash form.
- Windows: pi is stopped with child.kill (no process groups); run.py
  serve is stopped with taskkill /T; Git for Windows' diff is used for the
  Changes tab when diff is not on the PATH (FDEGYM_DIFF); spawns hide
  their windows; pnpm dev no longer sets API_PORT inline (cmd cannot) and
  the server keeps the API on 8787 under pnpm dev itself; engines node
  >=22.12 (Vite 8's native binding is skipped on older Node).
- Isolation label 'container' ("one container per run") in the start-up
  line and the admin runners page.
- Tests: sandbox-docker.test.ts (skipped without Docker); LocalProvider
  tests skip on Windows; test helpers clean up their sandboxes.
  Linux (node:22 + postgres:16): 42 pass, 6 skipped (no Docker there).
  Windows 11 + Docker Desktop 4.39, FDEGYM_SANDBOX=docker, Node 23:
  41 pass (pi, agent, runs, changes, Docker provider), 7 skipped.
- docs: self-hosting (Windows, settings), sandbox.md (the Docker provider).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@WaylandYang
WaylandYang merged commit 69e311a into dev Oct 18, 2026
5 checks passed
@WaylandYang
WaylandYang deleted the feat/sandbox-provider branch October 18, 2026 03:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant