# 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/`