Skip to content
Builderforce.ai Builderforce.ai BuilderForce Agents Docs

Sandbox CLI

Sandbox CLI

Section titled “Sandbox CLI”

Manage Docker-based sandbox containers for isolated agent execution.

Overview

Section titled “Overview”

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

Commands

Section titled “Commands”

builderforce sandbox explain

Section titled “builderforce sandbox explain”

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

Terminal window
builderforce sandbox explain
builderforce sandbox explain --session agent:main:main
builderforce sandbox explain --agent work
builderforce sandbox explain --json

builderforce sandbox list

Section titled “builderforce sandbox list”

List all sandbox containers with their status and configuration.

Terminal window
builderforce sandbox list
builderforce sandbox list --browser  # List only browser containers
builderforce 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

builderforce sandbox recreate

Section titled “builderforce sandbox recreate”

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

Terminal window
builderforce sandbox recreate --all                # Recreate all containers
builderforce sandbox recreate --session main       # Specific session
builderforce sandbox recreate --agent mybot        # Specific agent
builderforce sandbox recreate --browser            # Only browser containers
builderforce 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

Section titled “Use Cases”

After updating Docker images

Section titled “After updating Docker images”
Terminal window
# Pull new image
docker pull builderforce-sandbox:latest
docker tag builderforce-sandbox:latest builderforce-sandbox:bookworm-slim


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


# Recreate containers
builderforce sandbox recreate --all

After changing sandbox configuration

Section titled “After changing sandbox configuration”
Terminal window
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)


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

After changing setupCommand

Section titled “After changing setupCommand”
Terminal window
builderforce sandbox recreate --all
# or just one agent:
builderforce sandbox recreate --agent family

For a specific agent only

Section titled “For a specific agent only”
Terminal window
# Update only one agent's containers
builderforce sandbox recreate --agent alfred

Why is this needed?

Section titled “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 builderforce sandbox recreate to force removal of old containers. They’ll be recreated automatically with current settings when next needed.

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

Configuration

Section titled “Configuration”

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

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

See Also

Section titled “See Also”