Exploring the Latest in Docker Sandboxes Features
sbx command now shares one output layer. Table, JSON and YAML output are consistent, results go to stdout, diagnostics go to stderr, and confirmations behave the same everywhere.
That’s great for anyone who scripts sbx, but it is a breaking change. If you have CI jobs, Makefiles or wrapper scripts that call sbx ... --json | jq, read this post before you upgrade.
Everything below was run on macOS (Apple silicon) against sbx v0.48.0.
Prerequisites
sbx version
# sbx version v0.48.0 5caf923e0587d376848f6f388eca3e0f5ca00e2d
Upgrade with Homebrew (brew upgrade --cask sbx) or grab the installer from the sbx-releases v0.48.0 page.
Step 1: One flag for every format (--format table|json|yaml)
Every list/inspect-style command now takes --format. --json still works, but it is now just an alias for --format json.
sbx ls --format json
[
{
"name": "alpn-repro",
"id": "aa1735aa-5c64-415d-8b98-5b192deaa81a",
"agent": "shell",
"status": "stopped",
"last_used_at": "2026-09-08T14:49:59Z",
"workspaces": [
"/tmp/alpn-ws"
],
"created_at": "2026-09-08T14:49:59Z",
"workspace_missing": true,
"detached": true
}
]
Three things changed here:
- The top-level wrapper is gone.
sbx lsused to return{"sandboxes": [...]}. Now it returns the array directly. - Field names are
snake_case:created_at,last_used_at,workspace_missing. - Timestamps are RFC 3339, and every row has a
detachedboolean.
YAML is generated from the same representation, so the two formats can’t drift apart:
sbx rm demo-sandbox --force --format yaml
- action: removed
resource: sandbox
name: demo-sandbox
Step 2: The flags are now strict
The shared output flags are mutually exclusive, and a bad value now fails at flag parsing. Before, it silently fell back to the table view.
sbx ls --json --format json
error: if any flags in the group [format json] are set none of the others can be; [format json] were all set
try: sbx ls --help
sbx ls --format xml
error: invalid argument "xml" for "--format" flag: unknown format "xml"; use table, json or yaml
try: sbx ls --help
Both exit with status 1. That’s what you want in CI: a typo fails the job instead of handing jq a table.
Step 3: Mutating commands return machine-readable results
sbx rm, sbx stop, sbx template rm and sbx volume rm now return one result row per target in structured mode, including targets that failed:
sbx stop demo-sandbox does-not-exist --format json
[
{
"action": "stopped",
"resource": "sandbox",
"name": "demo-sandbox"
},
{
"action": "failed",
"resource": "sandbox",
"name": "does-not-exist",
"error": "runtime not found"
}
]
The command still exits with 1 because one target failed. The human-readable error: line goes to stderr, so stdout stays valid JSON:
sbx stop a b --format json 2>/dev/null | jq -r '.[] | select(.action=="failed") | .name'
The possible action values are lowercase: removed, stopped, removing, stopping, failed.
Step 4: The new sbx policy log schema
policy log has a single schema for local and cloud sandboxes: {updated_at, allowed: [...], blocked: [...]}. It replaces the old local allowed_hosts / blocked_hosts keys and the camelCase cloud document. --limit now applies to it.
sbx policy log agent-sandbox --format json --limit 3
{
"allowed": [
{
"sandbox_id": "agent-sandbox",
"host": "api.anthropic.com:443",
"proxy_type": "forward",
"count": 7,
"first_seen": "2026-10-17T10:06:31.327634+05:30",
"last_seen": "2026-10-17T10:06:33.200706+05:30"
}
],
"blocked": [
{
"sandbox_id": "agent-sandbox",
"host": "deb.debian.org:80",
"proxy_type": "forward",
"rule": "no applicable policies for op(action=net:connect:tcp, resource=net:domain:deb.debian.org:80)",
"reason": "No matching allow rule (default deny)",
"count": 3,
"first_seen": "2026-10-17T10:06:32.910874+05:30",
"last_seen": "2026-10-17T10:06:32.91639+05:30"
}
]
}
A one-liner that lists every host your agents were denied, which is handy when you’re tuning a network policy:
sbx policy log --format json | jq -r '.blocked[] | "\(.sandbox_id)\t\(.host)\t\(.count)"'
Step 5: More commands speak YAML
sbx diagnose, sbx prune --dry-run and cloud ttl all emit structured output now:
sbx diagnose --format yaml | head -15
version: "1.0"
checks:
- name: CLI binary
status: pass
message: found
detail: /opt/homebrew/Caskroom/sbx/0.48.0/Sbx.app/Contents/MacOS/sbx
hint: ""
- name: Binary version
status: pass
message: v0.48.0
detail: ""
hint: ""
- name: Daemon
status: pass
message: healthy
detail: version v0.48.0
sbx prune --dry-run --format json | jq -r '.would_remove[].name'
That’s a safe way to preview which stopped sandboxes prune would delete. sbx diagnose also takes --format github-issue, which produces a paste-ready bug report.
Step 6: Non-interactive behaviour (the change most likely to break CI)
Confirmation prompts require a real terminal now. Piping y into sbx no longer works:
echo y | sbx rm demo-sandbox
error: stdin is not a terminal; use --force to skip confirmation
Exit status is 1. The fix is to be explicit:
sbx rm demo-sandbox --force
Other non-TTY rules I confirmed:
- A missing workspace fails fast. You get a ready-made
mkdir -phint instead of a prompt:sbx create shell ./does-not-exist --name x1 </dev/nullerror: workspace directory /…/does-not-exist does not exist and stdin is not a terminal to ask about creating it try: mkdir -p /…/does-not-exist
- Answering “no” to a prompt always exits non-zero, including for
rm,resetandprune. - Read-only commands never start a browser sign-in. This covers
ports SANDBOX,ttl SANDBOX,prune --dry-run,diagnoseand anything run with--force. Runsbx loginbefore your automation starts. sbx diagnose --uploadwithout a TTY saves the bundle but skips the upload and still exits 0. A green exit doesn’t mean the upload happened.- Ctrl-D at a prompt now cancels instead of accepting the default.
Gotcha I hit: without a TTY,
sbx template savesays to “pass –force to skip the confirmation”, buttemplate savehas no--forceflag in 0.48.0. Until that’s fixed, run it from an interactive terminal (or underscript -q /dev/null …).
Step 7: Renamed flags cheat sheet
| Command | Old | New in 0.48.0 |
|---|---|---|
sbx run, sbx env run | --detached | --detach / -d (old flag is rejected) |
sbx logout | --yes, -y | --force, -f |
sbx env plan/create/run | --auto-approve, -y | --force, -f |
sbx create | --quiet, -q | --no-progress |
sbx template save | -d (description) | --description |
sbx diagnose | --output, -o | --format with table, json, yaml or github-issue |
sbx secret ls/rm | --env | --env-name |
sbx policy log | --quiet, -q | removed |
sbx mcp add | --skip_auth | --skip-auth (old spelling hidden, warns) |
Verify the hard rejection yourself:
sbx run --detached shell
error: unknown flag: --detached
try: sbx run --help
Step 8: Patch your jq filters
| Command | Old filter | New filter |
|---|---|---|
sbx ls --json | .sandboxes[].name | .[].name |
sbx template ls --json | .images[] | .[] |
sbx mcp ls --json | .servers[] | .[] (each row now carries .gateway) |
sbx ports --json (cloud) | .port | .sandbox_port |
sbx policy log --json | .blocked_hosts[] | .blocked[].host |
A quick way to find old filters across a repo:
grep -rnE "sbx .*--json.*\| *jq.*\.(sandboxes|images|servers|blocked_hosts|allowed_hosts)" .
Step 9: Don’t parse humans, parse streams
The table view changed too. It now has status marks, a CREATED column, and (detached) labels:
SANDBOX AGENT STATUS PORTS WORKSPACE CREATED
alpn-repro shell ○ stopped (detached) /tmp/alpn-ws 1mo
catalog-lab shell ○ stopped - 6d
Treat that view as UI, not as an API. Results go to stdout. Errors, warnings, hints, daemon start-up, image pulls and kit-build progress go to stderr. So this is always safe:
sbx ls --format json 2>/dev/null | jq length
# 32
Wrap-up
v0.48.0 makes sbx much nicer to script, provided you migrate:
- ☐ Replace
--detached→--detach,-y/--yes→--force - ☐ Update
jqfilters for array-shaped output andsnake_case - ☐ Remove every
echo y | - ☐ Capture stdout only when you parse results
- ☐
sbx loginbefore unattended jobs
Next up, Part 2: building a v3 kit with capability groups, kit.env, bundled agent skills, ssh-agent@1 and git-identity@1, all tested end to end.
References: Docker Sandboxes v0.48.0 release notes · Docker Sandboxes docs