mirror of https://github.com/hanzoai/bot.git synced 2026-10-30 17:24:26 +00:00

Files

T

zeekayandHanzo Dev 84e4069c2c docs name the state dir and config file the bot reads: ~/.bot/bot.json

The docs said ~/.hanzo-bot/hanzo-bot.json (and ~/.hanzo-bot-<profile>, hanzo-bot.plugin.json), which nothing reads: src/config/paths.ts resolves ~/.bot, bot.json and ~/.bot-<profile>, and plugins ship bot.plugin.json. Every such path in docs/ now names what the code opens.

Co-authored-by: Hanzo Dev <[email protected]>

2026-09-24 21:12:09 -07:00

4.2 KiB

Raw Permalink Blame History

title, summary, read_when, status

title	summary	read_when	status
Sandbox CLI	Manage sandbox containers and inspect effective sandbox policy	You are managing sandbox containers or debugging sandbox/tool-policy behavior.	active

Sandbox CLI

Manage Docker-based sandbox containers for isolated agent execution.

Overview

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

Commands

`hanzo-bot sandbox explain`

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

hanzo-bot sandbox explain
hanzo-bot sandbox explain --session agent:main:main
hanzo-bot sandbox explain --agent work
hanzo-bot sandbox explain --json

`hanzo-bot sandbox list`

List all sandbox containers with their status and configuration.

hanzo-bot sandbox list
hanzo-bot sandbox list --browser  # List only browser containers
hanzo-bot 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

`hanzo-bot sandbox recreate`

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

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

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

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

# Recreate containers
hanzo-bot sandbox recreate --all

After changing sandbox configuration

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

# Recreate to apply new config
hanzo-bot sandbox recreate --all

After changing setupCommand

hanzo-bot sandbox recreate --all
# or just one agent:
hanzo-bot sandbox recreate --agent family

For a specific agent only

# Update only one agent's containers
hanzo-bot 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 hanzo-bot sandbox recreate to force removal of old containers. They'll be recreated automatically with current settings when next needed.

Tip: prefer hanzo-bot 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 ~/.bot/bot.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": "hanzo-bot-sandbox:bookworm-slim",
          "containerPrefix": "hanzo-bot-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // Auto-prune after 24h idle
          "maxAgeDays": 7, // Auto-prune after 7 days
        },
      },
    },
  },
}

4.2 KiB Raw Permalink Blame History Unescape Escape