[jkyberneees]

Summary

Lets the Docker sandbox reach services started by Docker Compose (Redis, Postgres, Mongo, …) by name, and makes every sandbox decision fail closed and visible.

docker compose up -d
odek run --sandbox --sandbox-compose myapp "run the integration tests against redis and postgres"

What changes

Attaching existing Docker networks

• sandbox_networks (ODEK_SANDBOX_NETWORKS, --sandbox-networks a,b) attaches existing user-defined networks.
• sandbox_compose_project (ODEK_SANDBOX_COMPOSE_PROJECT, --sandbox-compose <project>) attaches every network carrying the project's com.docker.compose.project label. It never guesses <project>_default.
• What gets attached: only local bridge-driver networks, at most 8. A network is accepted only when docker network inspect returns the requested name, and it is passed to Docker by full ID. Reserved modes, container:/ns: forms and ID-prefix lookups are refused. No alias is added for the sandbox.
• How: the first network goes to docker run, the rest are connected after start, and the attachment is verified by inspect. Any failure removes the container. Networks are never deleted.
• Warnings: printed when a network is not Internal, or when bridge is combined with attached networks.
• Project config: a ./odek.json asking for networks goes through the existing sandbox-override approval. The prompt shows each network's name, full ID, Internal flag and Compose project. The approval key binds those IDs and is byte-identical to today's key for configs without networks. At container creation, the networks are checked again against the approved IDs: a network that joined the project, or was recreated, after the prompt is refused.
• Sub-agents only narrow: a child attaches a subset of its parent's resolved networks and never one its Compose project gained later.

What the agent is told

• An execution-environment block is appended to the system prompt on run, continue, repl, serve and sandboxed sub-agents, and to the shell tool description everywhere. It lists:
  • the container and /workspace;
  • the network the container actually has (none, bridge, attached networks only, bridge plus attached networks) and whether the internet is reachable;
  • the attached networks and the names other containers answer to there (Compose service aliases such as redis, postgres);
  • that localhost is the container itself.
• Network and service names can be chosen by a Compose file, so they are charset-checked, capped, and listed inside a nonce'd untrusted-content wrapper.
• The startup line and batch approval cards report the same network.

Fail-closed sandbox setup

• Configuration errors no longer fall back to the host. Before, a sandbox the user didn't explicitly request fell back to unsandboxed host execution on any setup error. Now any of these stops the run, whether or not --sandbox was passed:

  • an invalid sandbox_network;
  • an unresolvable network;
  • an image, limit or user value Docker rejects, or any other docker run failure while the daemon answers.

  Only an unreachable Docker daemon keeps the existing loud fallback (ODEK_REQUIRE_SANDBOX=1 still makes that fatal).

• sandbox_network accepts only none and bridge. host, container:… or a network name used to be silently rewritten to none; now it's an error. ODEK_SANDBOX_NETWORK_LENIENT=1 restores the downgrade.

Container defaults

• New defaults: --pids-limit 4096, configurable as sandbox_pids_limit / ODEK_SANDBOX_PIDS_LIMIT / --sandbox-pids-limit (a project may only lower it), plus --init, and nosuid on the /tmp tmpfs.
• Pinned fallback image: alpine:3.22@sha256:2e0b81d6…b55f instead of the floating alpine:latest.
  • It's read from an embedded internal/sandbox/default.Dockerfile, which Dependabot (docker ecosystem, /internal/sandbox only) keeps current.
  • tests/supplychain asserts the pin.
  • The multi-arch index digest was looked up with docker buildx imagetools inspect alpine:3.22.
• Settings visible: the startup line (odek: sandbox network=… pids=… image=… networks=…) and config_view (CLI tool and serve /api/config) show the settings actually applied.

Docs

• SANDBOXING.md:
  • new network-modes table;
  • attached networks, approval and re-check;
  • what the agent is told;
  • corrected the claim that bridge is isolated from host services: it reaches the Docker gateway, host-bound services and cloud metadata.
• CLI.md, CONFIG.md, SECURITY.md, DEVELOPMENT.md: new flags, env vars and config keys; the fail-closed rules.
• AGENTS.md: running the Docker-gated tests on Docker Desktop.

Behaviour changes to know about

• A sandbox_network value other than none/bridge now stops the run. Set ODEK_SANDBOX_NETWORK_LENIENT=1 for the old downgrade.
• An invalid image reference, a failed Dockerfile.odek build, or a memory, CPU or user value Docker rejects now stops implicit (default-on) runs instead of falling back to the host. An unreachable daemon or an image that cannot be pulled still falls back loudly.
• Sandboxed containers get a process limit of 4096 by default.
• With no image configured and no Dockerfile.odek, the sandbox runs the pinned alpine:3.22 digest instead of alpine:latest.

Testing

• Unit and regression tests:

  • Docker-dependent paths are covered through an injected docker runner.
  • New TestRED_* regression tests cover service-name aliases, the network label, the approval/setup ID re-check, exact-name resolution, start-failure classification, untrusted wrapping of names, the default-image parse and the sub-agent environment block.
  • security_report_validation_test.go gains the sandbox claims.

• Real Docker (Docker Desktop 29.6.2, scratch HOME, scripted mock model). A Compose project ran Redis on the normal network plus an internal: true backend network, and Postgres on the backend only.

  • --sandbox-compose:
    • redis and postgres resolve by service name, and Redis answers PONG;
    • the agent sees Network: attached networks only, Internet: reachable and postgres, redis;
    • pids.max is 4096, PID 1 is docker-init, and /tmp is nosuid,noexec;
    • the pinned digest is pulled and used.
  • --sandbox-networks <internal net>: services reachable, internet blocked. --sandbox-pids-limit 64 gives 64.
  • Refused with exit 1 and no host execution:
    • a missing network (with and without --sandbox);
    • --sandbox-network host;
    • bridge or container:x as a network name;
    • a bridge ID prefix (ca064c);
    • a Compose project that isn't running;
    • Docker unreachable while networks are configured;
    • --sandbox-memory lots in implicit mode.
  • An image that cannot be pulled (alpine:9.99-nonexistent) in implicit mode keeps the loud fallback.
  • Lenient mode downgrades with a warning.
  • A project odek.json requesting networks is refused without approval and attached once approved. The interactive prompt lists name, ID, internal flag and Compose project.

• Commands:

  • go test -count=1 for ./internal/sandbox ./internal/config ./internal/loop ./tests/supplychain ./cmd/odek: pass, with the Docker daemon both reachable and unreachable.
  • go test -race on the same packages: pass.
  • DOCKER_HOST=… ODEK_E2E=true go test ./cmd/odek -run 'TestSandbox|TestE2E_Sandbox': pass, nothing skipped.
  • golangci-lint run on the changed packages: 0 issues. govulncheck ./...: no vulnerabilities. gofmt -l: clean.

• Coverage: internal/sandbox 93.0% → 93.8%, internal/config 87.0% → 87.2%. Changed executable lines in cmd/odek: 84.7% (459/542).

• Review: an adversarial full-branch review (Opus) found three major issues, all fixed here:

  • setup failures that still fell back to the host;
  • an ID-prefix lookup that reached the default bridge;
  • Compose-chosen names reaching the system prompt unwrapped.

  Also fixed: two of its minor findings (the duplicated image pin that would break Dependabot bumps, the missing sub-agent environment block) and the wording of a third (how sub-agents narrow networks). A follow-up Sonnet pass on the fix commits found that an image that cannot be pulled had become fatal in implicit mode (now pulled separately and kept on the loud fallback) and that short service names that look like hex prefixes were dropped; both are fixed.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	c7f83a4	Commit Preview URL Branch Preview URL	Oct 25 2026, 12:22 PM