Sandbox CLI

Manage sandbox runtimes for isolated agent execution.

Overview

FluffBuzz can run agents in isolated sandbox runtimes for security. The sandbox commands help you inspect and recreate those runtimes after updates or configuration changes. Today that usually means:

Docker sandbox containers
SSH sandbox runtimes when agents.defaults.sandbox.backend = "ssh"
OpenShell sandbox runtimes when agents.defaults.sandbox.backend = "openshell"

For ssh and OpenShell remote, recreate matters more than with Docker:

the remote workspace is canonical after the initial seed
fluffbuzz sandbox recreate deletes that canonical remote workspace for the selected scope
next use seeds it again from the current local workspace

Commands

`fluffbuzz sandbox explain`

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

fluffbuzz sandbox explain
fluffbuzz sandbox explain --session agent:main:main
fluffbuzz sandbox explain --agent work
fluffbuzz sandbox explain --json

`fluffbuzz sandbox list`

List all sandbox runtimes with their status and configuration.

fluffbuzz sandbox list
fluffbuzz sandbox list --browser  # List only browser containers
fluffbuzz sandbox list --json     # JSON output

Output includes:

Runtime name and status
Backend (docker, openshell, etc.)
Config label and whether it matches current config
Age (time since creation)
Idle time (time since last use)
Associated session/agent

`fluffbuzz sandbox recreate`

Remove sandbox runtimes to force recreation with updated config.

fluffbuzz sandbox recreate --all                # Recreate all containers
fluffbuzz sandbox recreate --session main       # Specific session
fluffbuzz sandbox recreate --agent mybot        # Specific agent
fluffbuzz sandbox recreate --browser            # Only browser containers
fluffbuzz 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: Runtimes are automatically recreated when the agent is next used.

Use Cases

After updating a Docker image

# Pull new image
docker pull fluffbuzz-sandbox:latest
docker tag fluffbuzz-sandbox:latest fluffbuzz-sandbox:bookworm-slim

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

# Recreate containers
fluffbuzz sandbox recreate --all

After changing sandbox configuration

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)

# Recreate to apply new config
fluffbuzz sandbox recreate --all

After changing SSH target or SSH auth material

# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData

fluffbuzz sandbox recreate --all

For the core ssh backend, recreate deletes the per-scope remote workspace root on the SSH target. The next run seeds it again from the local workspace.

After changing OpenShell source, policy, or mode

# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy

fluffbuzz sandbox recreate --all

For OpenShell remote mode, recreate deletes the canonical remote workspace for that scope. The next run seeds it again from the local workspace.

After changing setupCommand

fluffbuzz sandbox recreate --all
# or just one agent:
fluffbuzz sandbox recreate --agent family

For a specific agent only

# Update only one agent's containers
fluffbuzz sandbox recreate --agent alfred

Why is this needed?

Problem: When you update sandbox configuration:

Existing runtimes continue running with old settings
Runtimes are only pruned after 24h of inactivity
Regularly-used agents keep old runtimes alive indefinitely

Solution: Use fluffbuzz sandbox recreate to force removal of old runtimes. They’ll be recreated automatically with current settings when next needed. Tip: prefer fluffbuzz sandbox recreate over manual backend-specific cleanup. It uses the Gateway’s runtime registry and avoids mismatches when scope/session keys change.

Configuration

Sandbox settings live in ~/.fluffbuzz/fluffbuzz.json under agents.defaults.sandbox (per-agent overrides go in agents.list[].sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, ssh, openshell
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "fluffbuzz-sandbox:bookworm-slim",
          "containerPrefix": "fluffbuzz-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // Auto-prune after 24h idle
          "maxAgeDays": 7, // Auto-prune after 7 days
        },
      },
    },
  },
}

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

Overview

Commands

`fluffbuzz sandbox explain`

`fluffbuzz sandbox list`

`fluffbuzz sandbox recreate`

Use Cases

After updating a Docker image

After changing sandbox configuration

After changing SSH target or SSH auth material

After changing OpenShell source, policy, or mode

After changing setupCommand

For a specific agent only

Why is this needed?

Configuration

See Also

​Overview

​Commands

​fluffbuzz sandbox explain

​fluffbuzz sandbox list

​fluffbuzz sandbox recreate

​Use Cases

​After updating a Docker image

​After changing sandbox configuration

​After changing SSH target or SSH auth material

​After changing OpenShell source, policy, or mode

​After changing setupCommand

​For a specific agent only

​Why is this needed?

​Configuration

​See Also

Overview

Commands

`fluffbuzz sandbox explain`

`fluffbuzz sandbox list`

`fluffbuzz sandbox recreate`

Use Cases

After updating a Docker image

After changing sandbox configuration

After changing SSH target or SSH auth material

After changing OpenShell source, policy, or mode

After changing setupCommand

For a specific agent only

Why is this needed?

Configuration

See Also