Skip to content

CLI reference

firebox <subcommand> [options]

Every subcommand is also a Python module — firebox.cli parses argv and dispatches. Tab-completion works under bash via firebox --print-completion bash (planned).

Global env vars

Var Default Notes
FIREBOX_URL http://spark-614c.local:8765 Where the daemon lives.
FIREBOX_TOKEN – Bearer secret. Falls back to ~/.firebox/token.
FIREBOX_SEARXNG_URL http://spark-614c.local:8888 Used by firebox search only.
FIREBOX_MODE – daemon or ssh. Defaults to daemon when a token is configured.

firebox doctor

Diagnoses the client install and the path to the daemon. Run after pip install:

✓ python                 3.11.x
• FIREBOX_URL            http://your-host:8765
✓ auth token             file ~/.firebox/token (49 bytes)
✓ daemon /healthz        {"ok": true, "ts": ...}
✓ searxng /healthz       OK
! mcp extra              not installed — `pip install firebox[mcp]` ...

Returns non-zero exit if anything's broken. Useful in CI.

firebox sandbox

firebox sandbox create [--template T] [--ttl N] [--vcpu N] [--mem N]
firebox sandbox run    <id> "shell command"  [--timeout N] [--cwd PATH]
firebox sandbox stream <id> "shell command"  [--timeout N] [--cwd PATH]
firebox sandbox close  <id>
firebox sandbox list

stream is the difference between waiting on a tail -f and watching it tick by — output lands on stdout/stderr line by line, exit code + duration come last.

firebox run / firebox run-many

One-shot batch microVMs (the VM is created, executes one command, then dies). Daemon-mode by default if a token is configured.

firebox run "uname -a"
firebox run-many "task1" "task2" "task3" --concurrency 5

For interactive long-running work prefer sandbox create + run.

firebox template

firebox template build -t <name> ./Dockerfile [--size GB]
firebox template list
firebox template rm <name>

Direct hit against FIREBOX_SEARXNG_URL — no microVM spawn, no token needed for the search itself (it's the operator's SearxNG).

firebox search "rust web framework"                           # 10 results, pretty
firebox search "AI agents"  -c news -t week  -n 5             # category + freshness
firebox search "playwright" -e brave,bing                     # specific engines
firebox search "calorie tracking" -l sl                       # locale
firebox search "..." --json                                   # machine-readable
firebox search "..." -u  | xargs -P5 curl -sI -o /dev/null    # pipe-friendly
firebox search "..." -T                                       # titles only
firebox search "..." --field engine | sort | uniq -c          # arbitrary field

firebox token (admin only)

firebox token list
firebox token create <id>                                     \
        [--admin]                                             \
        [--secret SECRET]                                     \
        [--max-sandboxes N]                                   \
        [--max-mem-mib N]                                     \
        [--max-ttl-seconds N]                                 \
        [--note "free text"]
firebox token revoke <id>

Calls /admin/*. Requires the calling token to have admin: true. The legacy bootstrap token is admin out of the box.

Exit codes

Code Meaning
0 success
1 runtime error (network unreachable, daemon refused, etc.)
2 argparse usage error
124 inside-sandbox timeout (matches timeout(1))
Pass-through of the in-VM command's own exit code when sandbox run succeeds