Sandbox CLI

Manage Docker-based sandbox containers for isolated agent execution.

Overview

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

Commands

`mayros sandbox explain`

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

bash
mayros sandbox explain
mayros sandbox explain --session agent:main:main
mayros sandbox explain --agent work
mayros sandbox explain --json

`mayros sandbox list`

List all sandbox containers with their status and configuration.

bash
mayros sandbox list
mayros sandbox list --browser  # List only browser containers
mayros 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

`mayros sandbox recreate`

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

bash
mayros sandbox recreate --all                # Recreate all containers
mayros sandbox recreate --session main       # Specific session
mayros sandbox recreate --agent mybot        # Specific agent
mayros sandbox recreate --browser            # Only browser containers
mayros 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
# Pull new image
docker pull mayros-sandbox:latest
docker tag mayros-sandbox:latest mayros-sandbox:bookworm-slim

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

# Recreate containers
mayros sandbox recreate --all

After changing sandbox configuration

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

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

After changing setupCommand

bash
mayros sandbox recreate --all
# or just one agent:
mayros sandbox recreate --agent family

For a specific agent only

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

Tip: prefer mayros 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 ~/.mayros/mayros.json under agents.defaults.sandbox (per-agent overrides go in agents.list[].sandbox):

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

Bash sandbox commands

The Bash Sandbox extension adds runtime command interception. These commands manage the sandbox's domain allowlists, command blocklists, and container isolation.

`mayros sandbox status`

Show current sandbox configuration, mode, and recent blocked commands.

bash
mayros sandbox status

`mayros sandbox test <command>`

Dry-run a command through the sandbox — returns the verdict (allowed/blocked/warned) with reasons.

bash
mayros sandbox test "rm -rf /"
mayros sandbox test "curl https://example.com/data"

`mayros sandbox allow <domain>`

Add a domain to the session allowlist (wildcards supported):

bash
mayros sandbox allow *.example.com
mayros sandbox allow api.internal.dev

`mayros sandbox deny <command>`

Add a command to the session blocklist:

bash
mayros sandbox deny dangerous-tool

`mayros sandbox container detect`

List available container runtimes (Docker, Podman, gVisor):

bash
mayros sandbox container detect

`mayros sandbox container status`

Show container sandbox configuration:

bash
mayros sandbox container status

`mayros sandbox container pull [image]`

Pull a container image for sandbox use:

bash
mayros sandbox container pull ubuntu:22.04

For full details on the Bash Sandbox, see Bash Sandbox.