stack/docs/plans/chroot-sandboxing.md

Chroot Agent Sandboxing — Process Isolation for Agent Tool Execution

Status: Stub — deferred. Referenced from 2026-03-15-agent-platform-architecture.md (Phase 7 Workspaces → Chroot Agent Sandboxing). Implement after Workspaces (P8-015) is complete. Requires workspace directory structure and WorkspaceService to be operational.

Date: 2026-03-15 Packages: apps/gateway

---

Problem Statement

Agent sessions can use file, git, and shell tools. Path validation in tools is defense-in-depth but insufficient alone — an agent with shell access can run cat /opt/mosaic/.workspaces/other_user/... and bypass gateway RBAC.

Chroot provides OS-level enforcement: tool processes literally cannot see outside their workspace directory.

---

Design (Sweet Spot)

Chroot strikes the balance between full container isolation (too heavy per session) and path validation only (escape-prone):

• Gateway spawns tool processes inside a chroot rooted at the session's sandboxDir
• Requires CAP_SYS_CHROOT capability on the gateway process (not full root)
• Chroot environment provisioned by WorkspaceService on workspace creation (minimal deps: git, shell utils, language runtimes as needed)
• Alternative for Docker deployments: Linux unshare namespaces (lighter, no chroot env setup)

---

Scope (To Be Designed)

• Chroot environment provisioning — WorkspaceService.provisionChroot(workspacePath) on project creation
• Minimal chroot deps — identify required binaries/libs per tool type (file: none; git: git binary; shell: bash, common utils)
• Gateway capability — document CAP_SYS_CHROOT requirement; Dockerfile and docker-compose.yml changes
• Tool process spawning — modify createShellTools, createFileTools, createGitTools to spawn via chroot wrapper
• Docker alternative — unshare --mount --pid --user namespace wrapper as fallback for environments without chroot capability
• Defense-in-depth layering — chroot + path validation both active; neither alone is sufficient
• Chroot cleanup — integrate with SessionGCService / workspace deletion
• AppArmor/SELinux profiles (v2) — restrict gateway process file access patterns for multi-tenant hardening

---

Security Constraints

• What lives inside the chroot (agent-accessible): workspace files, git repo, language runtimes
• What lives outside the chroot (gateway-only, never agent-accessible): Valkey connection, PG connection, other users' workspaces, gateway config, OTEL endpoint, credentials

---

Dependencies

• Workspaces (P8-015) — chroot is rooted at workspace directory; workspace must exist first
• Tool hardening (P8-016) — path validation stays active as defense-in-depth alongside chroot

---

References

• Original design context: docs/plans/2026-03-15-agent-platform-architecture.md → "Chroot Agent Sandboxing" section
• Current tool implementations: apps/gateway/src/agent/tools/