[saucam]

Summary

Two everyday workflows that the OS sandbox (#454) broke now work:

• Agents can create git worktrees. Each sandboxed session can add, commit in and remove worktrees in its own folder.
• Tests that start containers can use Docker, once you opt in.

Both keep the sandbox's guarantees, and the limits that remain are stated plainly.

Why

A real session hit both:

• Its agent never branches in the main checkout, because other agents share it. So it runs git worktree add, which failed with "Operation not permitted" under .git/worktrees/.
• Its tests start MySQL and Postgres through testcontainers. That needs the Docker socket, which the sandbox hides because Docker access is root-equivalent.

Worktrees: one folder per session

• Where a session may create worktrees. Only under its own folder of the repository's worktree locations: <repo>-worktrees/<session-folder>/…, plus any sandbox.worktreeRoots entries, scoped per repository. Codeoid tells the agent the path when the session starts.
  • The folder name is stable across resume and daemon restarts.
  • A fork gets its own.
  • Inside it, git worktree add, commit, rebase, remove and prune all work, in every mode.
• What stays read-only: everything else there. That covers your own worktrees, other sessions' folders, codeoid's fork, loop and --worktree checkouts, and any folder created later by anyone else.
• Continuing another session's worktree: start a session in it. It's then that session's workspace, and writable.
• Git's bookkeeping (.git/worktrees/) stays protected:
  • entries that exist when the sandbox is built are read-only and pinned;
  • every entry that isn't the session's own is checked against git's own layout when the sandbox is built and at the end of every turn;
  • a tampered entry is restored and announced on the session (session.worktree_entry_restored in the audit log).
• Nothing is created inside your checkout. The session's sibling folder is removed again when it's empty.
• sandbox.worktreeRoots is validated after resolving. It refuses your home, /, and any dir whose contents run outside the sandbox (~/.config, ~/.local, systemd units, LaunchAgents, codeoid's dirs).
• Adding or removing a worktree never rebuilds another session's sandbox. Earlier drafts of this change did that, and it killed Claude sessions' CLIs.
• Documented limit: between a takeover of an entry created while the session runs and that turn's end, git in that checkout could follow the planted entry. The end-of-turn check restores it.

Docker access: opt-in

• How to turn it on: sandbox.docker.socket, off by default. It's in Settings → Sandbox, CODEOID_SANDBOX_DOCKER_SOCKET, per session /sandbox auto docker, codeoid new … --docker-socket, and the new-session dialog.
  • Turning it on is an owner-confirmed widening, with the same authority rules as turning the sandbox off.
  • The session shows "sandboxed, Docker access", because Docker access can reach the whole machine.
• What a command gets:
  • the runtime's socket, read-only, so it can't remove or replace it;
  • DOCKER_HOST set to that socket. The user's own (rootless) runtime is preferred over the root daemon's.
• What stays hidden: registry logins (~/.docker/config.json).
• Per provider:
  • bubblewrap and Seatbelt expose the socket;
  • the Docker provider mounts it into the container;
  • on Claude's Linux sandbox, the CLI only allows unix sockets all-or-nothing. So with Docker access on, the host's /tmp and other shared socket dirs are hidden, and the runtime's socket is the only one reachable.

Also tightened

• Root-equivalent sockets hidden in every sandbox: libvirt, LXD, Incus, containerd, k3s and the system bus. They were reachable before.
• With the network off or an allowlist, local services' sockets are hidden too: Postgres, MySQL and Redis, whose peer authentication needs no password.

Verification

• Reviews: two deep review rounds, each with three sandboxed reviewers. The findings changed the design to per-session folders, then to the end-of-turn integrity check. Everything they found is fixed, and each fix has a regression test confirmed to fail without it.
• Fresh install on CI's Bun 1.3.13: typecheck and lint are clean. The full suite has 5,792 pass and 0 fail, and all 16 e2e specs pass against a fresh web build. Web tests show the same 39 environment failures as main.
• Real bubblewrap: create, commit and remove in the session's folder works; writing elsewhere, into other sessions' folders or into existing entries fails; a takeover is restored; planted sockets are hidden or exposed as configured.
• Real Docker: 13 of 13 pass.
• Not verified: macOS (Seatbelt rules for both features). They're added to the checklist in docs/sandbox.md.

---

🤖 Implementation context (for agents / maintainers)

• src/daemon/sandbox/policy.ts: worktree locations and the per-session folder; worktreeRoots validation and per-repo scoping; dockerSocketPaths (order: DOCKER_HOST, the user's runtime, then system); hidden runtime and service sockets (HOST_SOCKET_DIRS); git layout pinning.
• The worktree integrity check and restore, run at sandbox build, turn end and destroy, with session.worktree_entry_restored. See the round-11 fix commit.
• Providers: bwrap.ts, seatbelt.ts, docker.ts, claude-native.ts (allowAllUnixSockets with Docker access, plus the narrowing).
• Surfaces: SessionSandboxInfo.dockerSocket and limits lines, core sandboxBadge, web SandboxChip / NewSessionModal / settings, CLI --docker-socket, /sandbox … docker.
• Docs: docs/sandbox.md ("Git worktrees inside the sandbox", "Docker access"), CHANGELOG, CLAUDE.md.

🤖 Generated with Claude Code