smart-org/docs/plan/reports/agent-3-phase-1.md

Agent 3 — Phase 1 report: Docker sandbox adapter

Date: 2026-10-13 · Branch: dev (work done directly on dev; see "Deviations")

What was done

1.1 DockerSandboxAdapter (app/infrastructure/adapters/docker_sandbox.py)

Implements SandboxProviderPort over the docker/podman CLI, with the binary taken from SANDBOX_DOCKER_BIN so podman is a drop-in (the flags used are the common subset).

• create_workspace — creates SANDBOX_WORKSPACES_ROOT/<org>/<project>/work at 0700, and encodes the workspace identity in the external id (ws-<org>-<project>) so a restarted process can rebuild the host paths without a database round-trip. One workspace per application, per D5.
• start_session — docker run -d with the full hardening set: --user 1000:1000, --cap-drop ALL, --security-opt no-new-privileges, --pids-limit 512, --cpus, --memory, --read-only + --tmpfs /tmp + --tmpfs /home/app, a single bind mount of the work dir at /workspace, labels smart-org.org / smart-org.project / smart-org.role, default bridge network and no published ports. It reuses an existing container of the same name rather than stacking duplicates after a restart.
• run_command — docker exec -w <cwd> <ctr> sh -lc <cmd>. cwd and on_output are adapter-level extras for the engine; the port signature is unchanged. Environment variables are passed with -e, and any key that looks like a secret is refused — argv is visible in ps, so credentials must never travel that way.
• read_file / write_file — through the host bind mount, with safe_join path safety (rejects .., absolute escapes and symlinks that resolve outside the work dir).
• pause / resume / destroy — stop / start / rm -f -v.
• snapshot — docker commit, documented as capturing the root filesystem only (the work tree is a bind mount and is not included).
• get_preview_url — http://127.0.0.1:<port>, and it refuses a platform-protected port.
• Extras used by later phases: start_demo_container (loopback-only publish, same hardening, role=demo), list_managed_containers, remove_container, host_dir_for, binary_available, plus the module-level image_for_language map (node:20-bookworm, python:3.13-bookworm, php:8.3-cli, golang:1.23, debian:bookworm fallback).

1.1a app/infrastructure/adapters/process.py (new, shared)

The one place the platform shells out. run_process exists to make four failure modes impossible:

• shell injection — create_subprocess_exec with an argv list, never shell=True;
• orphaned children — start_new_session=True and killpg on timeout (SIGTERM then SIGKILL), so a docker build's helpers die with it;
• pipe deadlock — stdout and stderr drained concurrently by two tasks, with a byte cap applied while streaming (the callback still sees every chunk, so live logs stay complete);
• secret inheritance — an explicit minimal env (a handful of safe keys), never os.environ wholesale.

A missing binary returns spawn_failed=True rather than raising; a non-zero exit or a timeout is an ordinary result the caller inspects.

1.2 Registry

get_sandbox_provider() now maps SANDBOX_PROVIDER=docker to the adapter (cached as a singleton so the workspace registry stays consistent between create_workspace and the start_session that follows). mock remains the default; daytona/e2b are unchanged.

1.3 Orphan reaping

SandboxGatewayWorker.reap_orphans() lists every container carrying our labels and removes any whose id is not in SandboxSessionRepository.list_active_external_ids() (new method). Each removal is audited as sandbox.reap with reason=orphan_container. A provider without list_managed_containers is skipped silently. SandboxGatewayWorker.run_pass() runs idle-session reaping and orphan reaping in one pass, and workers/__main__.py now calls it.

1.4 Infrastructure hidden from non-owners

app/interfaces/http/routers/sandbox.py: every mutating route now requires the platform owner via a local _require_platform_owner(context) helper — create/destroy workspace, start/stop session, run command, read/write file, snapshot, preview URL, set limits. The read-only status routes (templates, effective limits, workspace list, command log) stay open to org members, because the project page shows them.

components/sandbox-panel.tsx takes a canManageInfra prop (default false, so a call site that forgets it fails closed). A non-owner sees the limits card, the workspace list and a short note that infrastructure is managed by the platform owner; the create form, the session panel and the per-workspace action buttons are not rendered at all (not merely disabled). (app)/projects/[id]/page.tsx passes canManageInfra={user?.is_platform_owner ?? false}.

Files changed

File	Change
app/infrastructure/adapters/process.py	new — hardened host subprocess runner
app/infrastructure/adapters/docker_sandbox.py	new — the docker/podman sandbox adapter
app/infrastructure/adapters/registry.py	SANDBOX_PROVIDER=docker branch
app/infrastructure/repositories/sandbox.py	list_active_external_ids()
app/workers/sandbox_gateway.py	reap_orphans(), run_pass()
app/workers/__main__.py	sandbox-gateway pass calls run_pass()
app/interfaces/http/routers/sandbox.py	owner-only mutating routes
tests/test_docker_sandbox.py	new — 37 tests
tests/test_workers.py	2 sandbox tests now use a platform-owner org
tests/test_e2e_smoke.py	smoke path signs up as the platform owner
apps/web/src/components/sandbox-panel.tsx	canManageInfra gating
apps/web/src/app/(app)/projects/[id]/page.tsx	passes the owner flag
apps/web/src/test/delivery-sandbox-panel.test.tsx	new — 3 tests
.gitignore	.pytest-tmp/

Test output

apps/api:  346 passed (was 309; +37)
           ruff check .  -> All checks passed!
           mypy app      -> Success: no issues found in 127 source files
apps/web:  67 passed (was 64; +3)
           tsc --noEmit  -> clean
           next lint     -> No ESLint warnings or errors

Deviations from the TODO

1. No worktrees. The plan's environment (exFAT /projects, ext4 worktrees under /home/mamad/work/) describes a Linux box. This machine is macOS with the repo at /Users/mamad/Projects/agy-bot/web; all work is done on dev and committed per phase.
2. Owner-only rather than "admin+ with a setting". The TODO offered both; owner-only is the stated preference and matches "users never touch infrastructure" (PLAN-v2 §1.9).
3. Test updates. Making sandbox mutation owner-only breaks three existing tests that drove those routes as a plain manager. test_e2e_smoke.py and the two sandbox-gateway tests in test_workers.py now sign up as the platform owner. No assertion was weakened; only the actor's platform role changed.
4. tmp_path needs a writable TMPDIR on this machine. The pre-existing $TMPDIR/pytest-of-unknown directory is rejected by the local sandbox broker, so pytest cannot create its base temp dir. Tests are run with TMPDIR=<repo>/.pytest-tmp/tmproot (now gitignored). This is an environment quirk, not a code change.

Open questions / CHANGE REQUESTS

• None. RepoWorkspacePort, DeliveryHooks and DeployTargetTester are consumed exactly as frozen; the docker adapter adds methods rather than changing the port.

Known limitations

• The workspace registry (external id → image) is process-local. A cold process rebuilds the host dir from the encoded external id but falls back to the default image; in practice create_workspace and start_session happen in the same request.
• snapshot does not capture the work tree (bind mount). Documented in the docstring.
• No @pytest.mark.docker integration test yet; the fake runner covers the argv contract, which is where the security properties live. A live round-trip is added in Phase 3, where the build/demo containers make it meaningful.