# Sandboxing Overview

Anteroom provides layered controls to limit what the `bash` tool can do on your system. These controls fall into two categories: **policy-enforced checks** (all platforms) and **OS-level resource limits** (Windows only, via Win32 Job Objects).

This page explains the architecture, what is enforced on each platform, and what is not sandboxed today.

For bash-specific config fields, see [Bash Sandboxing](bash-sandboxing.md). For risk tiers and approval gates, see [Tool Safety](tool-safety.md).

---

## Sandbox Model

Anteroom's sandbox is a **two-layer model**:

### Layer 1 — Policy Enforcement (all platforms)

Policy checks execute before a command is handed to the shell. If a check fails, the command is blocked before any subprocess is created. These checks run on Windows, macOS, Linux, and WSL.

Policy checks include:

- **Hard-block patterns** — 16 unconditionally blocked command patterns (`rm -rf`, `mkfs`, fork bombs, pipe-to-shell, etc.). Cannot be overridden by config or approval.
- **Destructive patterns** — commands like `rm`, `git reset --hard`, and `DROP TABLE` that trigger approval prompts unless the user is in `auto` mode.
- **Path controls** — blocked paths (exact or prefix), allowed paths allowlist, hardcoded system path blocks (`/etc/shadow`, `/proc/*`, etc.), and symlink resolution to prevent traversal.
- **Command controls** — custom regex patterns that reject or prompt before specific commands.
- **Network detection** — optionally blocks `curl`, `wget`, `ssh`, PowerShell web commands, and similar tools when `allow_network: false`.
- **Package install detection** — optionally blocks `pip install`, `npm install`, `apt install`, and similar commands when `allow_package_install: false`.
- **Execution limits** — per-command timeout (default 120s) and output truncation (default 100,000 characters).
- **Approval gates** — tool risk tiers (READ / WRITE / EXECUTE / DESTRUCTIVE) and approval mode determine whether the user must confirm before any tool executes.

### Layer 2 — OS-Level Resource Limits (Windows only)

On Windows, Anteroom can assign bash subprocesses to a **Win32 Job Object**, providing kernel-level resource limits:

- Peak memory cap per job
- Maximum child process count
- Optional CPU time budget

The Win32 Job Object sandbox is **not available on macOS or Linux**. See [What Is Not Sandboxed Today](#what-is-not-sandboxed-today).

---

## Platform Support Matrix

| Platform | Policy checks | Hard-block patterns | Approval gates | OS-level resource limits | Filesystem isolation |
|---|---|---|---|---|---|
| **Windows** | Yes | Yes | Yes | Yes (Win32 Job Objects) | No |
| **macOS** | Yes | Yes | Yes | No | No |
| **Linux** | Yes | Yes | Yes | No | No |
| **WSL** | Yes | Yes | Yes | No (runs as Linux inside WSL) | No |

**Policy checks** = path controls, command controls, network/package detection, timeout, output limits.
**Approval gates** = tier-based user confirmation before execution.
**OS-level resource limits** = kernel-enforced memory, process count, and CPU time caps.
**Filesystem isolation** = sandboxed filesystem namespace (seccomp/Landlock/App Sandbox). Not yet implemented on any platform; tracked in issue #231.

---

## Sandbox Layers — Execution Order

When the `bash` tool is called, checks run in this order:

```
1. Hard-block patterns       — unconditional, no override possible
2. Destructive patterns      — triggers approval (except auto mode)
3. Path controls             — blocked_paths, allowed_paths, hardcoded blocks
4. Command controls          — blocked_commands, custom_patterns
5. Network detection         — blocked if allow_network: false
6. Package install detection — blocked if allow_package_install: false
7. Approval gate             — tier check against approval_mode
8. Subprocess creation       — command handed to the shell
9. OS-level resource limits  — Win32 Job Object applied (Windows only)
```

A command blocked at any step never reaches a later step. The shell subprocess is never created for policy-blocked commands.

### Graceful Degradation (Win32 Job Object)

If Win32 Job Object creation fails at runtime (insufficient privilege, API error, unsupported Windows edition), Anteroom logs a warning and continues without the OS sandbox. The command still runs subject to policy checks (layers 1–7) and the configured timeout. The behavior degrades gracefully — the sandbox failure does not block the command or crash the agent loop.

The `sandbox.enabled` config field defaults to `null` (auto-detect). Set `enabled: true` to require the sandbox (commands are blocked if job object creation fails) or `enabled: false` to disable it explicitly.

---

## What Is Not Sandboxed Today

Anteroom's current sandbox model has explicit limits. These are not bugs — they reflect the current scope of the implementation.

### No filesystem namespace isolation (all platforms)

The `bash` tool runs as the same OS user as the Anteroom process. There is no `chroot`, `seccomp`, Landlock (Linux), or App Sandbox (macOS) equivalent. The AI can read and write any file the OS user has access to, subject to path controls and approval gates.

This means:

- Path controls (`blocked_paths`, `allowed_paths`) are policy checks, not kernel enforcement. A sufficiently creative command that bypasses path-pattern matching could still access those paths.
- Hard-block patterns are string-pattern checks, not syscall-level enforcement. They protect against known destructive patterns, not arbitrary shell techniques.

Codex-style `read-only` / `workspace-write` / `full-access` filesystem modes backed by kernel enforcement are tracked in issue #231 and are not yet implemented.

### No OS-level resource limits on macOS and Linux

Win32 Job Objects are a Windows-only primitive. Anteroom does not currently use `cgroups` (Linux), `setrlimit`, or other OS-level resource mechanisms on non-Windows platforms. Execution limits (timeout, output size) are enforced by the Anteroom process, not the kernel.

### No network namespace isolation

The `allow_network: false` config blocks known network tools by pattern matching. It does not prevent a script from using raw sockets, an unusual tool, or a compiled binary that makes network connections.

---

## Configuration Summary

### `safety.bash.*` — policy controls

| Field | Default | Description |
|---|---|---|
| `enabled` | `true` | Enable/disable bash tool entirely |
| `timeout` | `120` | Per-command timeout in seconds (1–600) |
| `max_output_chars` | `100000` | Max output characters (min 1000) |
| `blocked_paths` | `[]` | Path prefixes to block |
| `allowed_paths` | `[]` | Allowed path prefixes (empty = allow all) |
| `blocked_commands` | `[]` | Custom regex patterns to block |
| `allow_network` | `true` | Allow known network tools |
| `allow_package_install` | `true` | Allow package manager invocations |
| `log_all_commands` | `false` | Log all commands to audit log |

### `safety.bash.sandbox.*` — OS-level limits (Windows only)

| Field | Default | Description |
|---|---|---|
| `enabled` | `null` | `null` = auto-detect, `true` = require, `false` = disable |
| `max_memory_mb` | `512` | Peak memory per job (min 64 MB) |
| `max_processes` | `10` | Max child processes (1–1000) |
| `cpu_time_limit` | `null` | CPU seconds limit (null = no limit) |

See [Bash Sandboxing](bash-sandboxing.md) for the full configuration reference and examples.
