Join our Discord Server
Collabnix Team The Collabnix Team is a diverse collective of Docker, Kubernetes, and IoT experts united by a passion for cloud-native technologies. With backgrounds spanning across DevOps, platform engineering, cloud architecture, and container orchestration, our contributors bring together decades of combined experience from various industries and technical domains.

What’s New in Docker Sandboxes 0.48.0? One Output Format for Every Command

4 min read

What’s New in Docker Sandboxes 0.48.0? One Output Format for Every Command

Exploring the Latest in Docker Sandboxes Features

Docker Sandboxes v0.48.0 shipped on 13 October 2026. The biggest change isn’t a new command. Every 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:

  1. The top-level wrapper is gone. sbx ls used to return {"sandboxes": [...]}. Now it returns the array directly.
  2. Field names are snake_case: created_at, last_used_at, workspace_missing.
  3. Timestamps are RFC 3339, and every row has a detached boolean.

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 -p hint instead of a prompt:
    sbx create shell ./does-not-exist --name x1 </dev/null
    error: 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, reset and prune.
  • Read-only commands never start a browser sign-in. This covers ports SANDBOX, ttl SANDBOX, prune --dry-run, diagnose and anything run with --force. Run sbx login before your automation starts.
  • sbx diagnose --upload without 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 save says to “pass –force to skip the confirmation”, but template save has no --force flag in 0.48.0. Until that’s fixed, run it from an interactive terminal (or under script -q /dev/null …).

Step 7: Renamed flags cheat sheet

CommandOldNew 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, -qremoved
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

CommandOld filterNew 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 jq filters for array-shaped output and snake_case
  • ☐ Remove every echo y |
  • ☐ Capture stdout only when you parse results
  • ☐ sbx login before 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

Have Queries? Join https://launchpass.com/collabnix

Collabnix Team The Collabnix Team is a diverse collective of Docker, Kubernetes, and IoT experts united by a passion for cloud-native technologies. With backgrounds spanning across DevOps, platform engineering, cloud architecture, and container orchestration, our contributors bring together decades of combined experience from various industries and technical domains.

Understanding AI Embeddings and Vector Search for Beginners

Explore the world of AI embeddings and vector search, learning how they transform massive data into actionable insights, driving intelligent systems.
Collabnix Team
9 min read
Join our Discord Server