sandboxd, sbx diagnose, and sbx reset

sbx ls hangs, or a command fails with ensure daemon: daemon exited unexpectedly, and you need to know which process answers, where it writes, and how to start over. Every verb in this part talks to one host daemon, sandboxd, over a Unix socket. When you finish this section, you can find the socket and the log, read the thirteen checks of sbx diagnose, and say what sbx reset deletes.

sandboxd

sandboxd: the host daemon behind every local sbx verb, managed with sbx daemon start, stop, restart, status, and log-level set. The settings commands use the local daemon to read evaluated values and manage overrides, and they start it when it is not running. So the first probe of sbx settings list printed Starting sandboxd daemon... before its table. sbx daemon start -d runs it in the background. --policy allow-all, balanced, or deny-all initializes the global network policy at the same time, which sbx policy init covers. sbx daemon log-level set TARGET LEVEL changes one log category, proxy, general, or all.

sbx daemon status --json names the socket and the log, both under ~/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/ on the recording Mac, where $HOME is a capture mask.

{
  "status": "running",
  "socket": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/sandboxd.sock",
  "logs": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/sandboxd/daemon.log"
}

The log is JSON lines with time, level, msg, version, and often a runtime, the sandbox name, and the lifecycle section reads two of them. Since v0.43.0 the local daemon checks the operating-system user of each connection on Unix sockets and Windows named pipes. Since v0.46.0 a second daemon on a state directory that is in use fails with an error and leaves the running daemon alone.

The state directory

State directory: the tree where sandboxd keeps sandboxes, images, policies, and its socket. On macOS it is ~/Library/Application Support/com.docker.sandboxes/, on Windows %LOCALAPPDATA%\DockerSandboxes, and on Linux the state is in three directories: ~/.local/state/sandboxes/, ~/.cache/sandboxes/, and ~/.config/sandboxes/. Release v0.29.0 added the SANDBOXES_STORAGE_ROOT override, and v0.31.0 moved the state directory symlink from /tmp to ~/.sbx/run/. The daemon binds its containerd socket under that symlink. The sbx kit builder history help pages, captured in a shell that could not bind sockets, end in failed to create unix socket on $HOME/.sbx/run/d/containerd/containerd.sock.ttrpc.

Two more trees matter. The first is the shared skills store at sandboxes/agent-skills under the state directory. The second is the audit log under ~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/, where each file is named audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl. The 2025 plugin kept its VMs under ~/.docker/sandboxes/vm/ and its images under ~/.docker/sandboxes/image-cache/, which the migration section maps. Figure 2.3 draws the macOS tree, and the settings table lists every path for the three systems.

sbx diagnose

sbx diagnose runs thirteen checks in four groups and prints a pass, a warning, or a failure for each. Installation finds the binary, its version, the daemon, and a diagnostics bundle. Platform confirms kern.hv_support is 1 and finds mkfs.erofs with its default block size and the guest kernel page size. Storage checks the state directory, its permissions, and the free space. Connection checks the version match, the socket, the SSH client config, and the sign-in.

The page-size check exists because v0.43.0 made diagnose warn when its default block size is larger than the page size of the sandbox kernel. On the recording Mac the block size is 4096 bytes and the guest page size is 16384 bytes, which getconf PAGESIZE inside m101-demo confirms.

{
  "version": "1.0",
  "checks": [
    …
    {
      "name": "Virtualization",
      "status": "pass",
      "message": "supported",
      "detail": "kern.hv_support is 1",
      "hint": ""
    },
    {
      "name": "mkfs.erofs",
      "status": "pass",
      "message": "found",
      "detail": "/opt/homebrew/Caskroom/sbx/0.47.0/Sbx.app/Contents/libexec/mkfs.erofs, default block size <n> bytes, guest kernel page size <n> bytes",
      "hint": ""
    },
    …
  ],
  "summary": {
    "pass": 13,
    "warn": 0,
    "fail": 0,
    "skip": 0
  }
}

--json gives a version, a checks array with name, status, message, detail, and hint, and a summary with pass, warn, fail, and skip counts. -o github-issue formats the same report for a bug report, and --upload sends a bundle to Docker support. diagnostics.autoUpload in sbx settings list is the consent for automatic uploads.

sbx reset

sbx reset returns the install to a freshly installed state, and the help lists the steps:

• stop running sandboxes, with a 30 s timeout
• clear the image cache and the internal registries
• delete all sandbox state and all policies
• remove the managed SSH configuration
• clear the sessions and the history of the Gordon assistant
• delete stored secrets, unless --preserve-secrets
• sign out, stop the daemon, and remove the state, cache, and config directories

The docs give Gordon no role in a sandbox, so this manual repeats that one item and claims nothing more, as conflict C33 rules. The docs use the command after an upgrade. A newer sbx can move the local database to a schema that older binaries cannot read. Then --preserve-secrets keeps your secrets through that.

The last resort is to delete the state directory by hand after sbx reset. Your workspaces stay where they are. The docs say that host workspace files stay on your host when a sandbox is removed, and sbx reset lists only state, cache, and config directories. Commands that help text names but the help tree does not list, such as sbx mount, are collected in sbx settings list.