> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sandbox

# `fased sandbox`

Manage Docker-based sandbox containers for isolated agent execution and inspect
the effective sandbox policy that the runtime is actually applying.

## Overview

Fased can run agents in isolated Docker containers for security. The `sandbox`
commands help you manage these containers, especially after updates or
configuration changes.

## Commands

### `fased sandbox explain`

Inspect the **effective** sandbox mode, scope, workspace access, sandbox tool
policy, and elevated gates with fix-it config key paths.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased sandbox explain
fased sandbox explain --session agent:main:main
fased sandbox explain --agent work
fased sandbox explain --json
```

### `fased sandbox list`

List all sandbox containers with their status and configuration.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased sandbox list
fased sandbox list --browser  # List only browser containers
fased sandbox list --json     # JSON output
```

**Output includes:**

* Container name and status (running/stopped)
* Docker image and whether it matches config
* Age (time since creation)
* Idle time (time since last use)
* Associated session/agent

### `fased sandbox recreate`

Remove sandbox containers to force recreation with updated images/config.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased sandbox recreate --all                # Recreate all containers
fased sandbox recreate --session main       # Specific session
fased sandbox recreate --agent mybot        # Specific agent
fased sandbox recreate --browser --all      # Only browser containers
fased sandbox recreate --all --force        # Skip confirmation
```

**Options:**

* `--all`: Recreate all sandbox containers
* `--session <key>`: Recreate container for specific session
* `--agent <id>`: Recreate containers for specific agent
* `--browser`: Only recreate browser containers
* `--force`: Skip confirmation prompt

**Important:** Containers are automatically recreated when the agent is next used.

## Use Cases

### After updating Docker images

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Pull new image
docker pull fased-sandbox:latest
docker tag fased-sandbox:latest fased-sandbox:bookworm-slim

# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)

# Recreate containers
fased sandbox recreate --all
```

### After changing sandbox configuration

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)

# Recreate to apply new config
fased sandbox recreate --all
```

### After changing setupCommand

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased sandbox recreate --all
# or just one agent:
fased sandbox recreate --agent family
```

### For a specific agent only

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Update only one agent's containers
fased sandbox recreate --agent alfred
```

## Why is this needed?

**Problem:** When you update sandbox Docker images or configuration:

* Existing containers continue running with old settings
* Containers are only pruned after 24h of inactivity
* Regularly-used agents keep old containers running indefinitely

**Solution:** Use `fased sandbox recreate` to force removal of old containers.
They will be recreated automatically with current settings when next needed.

Tip: prefer `fased sandbox recreate` over manual `docker rm`. It uses the
Gateway’s container naming and avoids mismatches when scope/session keys change.

## Configuration

Sandbox settings live in `~/.fased/fased.json` under
`agents.defaults.sandbox`. Per-agent overrides go in `agents.list[].sandbox`.

```jsonc theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "fased-sandbox:bookworm-slim",
          "containerPrefix": "fased-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // Auto-prune after 24h idle
          "maxAgeDays": 7, // Auto-prune after 7 days
        },
      },
    },
  },
}
```

## See Also

* [Sandbox Documentation](/gateway/sandboxing)
* [Agent Configuration](/concepts/agent-workspace)
* [Doctor Command](/gateway/doctor) - Check sandbox setup