Docker Sandboxes Wouldn't Start? Check Your XDG Directories

Docker Sandboxes Wouldn't Start? Check Your XDG Directories

I recently started experimenting with Docker Sandboxes while setting up Codex on an Ubuntu 24.04 server. Installation was straightforward, but every attempt to launch a sandbox failed with:

ERROR: ensure daemon: daemon failed to start properly after 10 retries

The first place I looked was the daemon log. Surprisingly, it ended with:

starting api server
api server started successfully

That immediately raised a question:

If the daemon believes it started successfully, why does the client insist that it didn't?

Tested Environment

My home directory resides on a ZFS dataset:

findmnt -T /mnt/tom

TARGET   SOURCE   FSTYPE
/mnt/tom VD02/tom zfs

Symptoms

Running:

sbx diagnose

reported:

✗ Daemon — not reachable

However, the daemon log consistently reported:

api server started successfully

A direct health check also succeeded:

curl --unix-socket ~/.local/state/sandboxes/sandboxes/sandboxd/sandboxd.sock \
http://localhost/daemon/health

The daemon appeared healthy.

What Are XDG Directories?

Modern Linux applications generally follow the XDG Base Directory Specification, which defines standard locations for configuration, cache, application data, persistent state, and runtime objects.

Since my home directory lived on ZFS, all of these default locations (except XDG_RUNTIME_DIR) also lived on ZFS.

The Workaround

As an experiment, I redirected the XDG directories to /var/tmp:

export XDG_CONFIG_HOME="/var/tmp/sbx-$UID/config"
export XDG_CACHE_HOME="/var/tmp/sbx-$UID/cache"
export XDG_DATA_HOME="/var/tmp/sbx-$UID/data"
export XDG_STATE_HOME="/var/tmp/sbx-$UID/state"

# Keep runtime sockets in the standard location.
export XDG_RUNTIME_DIR="/run/user/$UID"

Immediately afterwards, sbx diagnose changed from reporting the daemon as unreachable to:

✓ Daemon — healthy
✓ Version match
✓ Socket — responsive

After logging in:

sbx login

Codex launched normally.

A Cleaner Solution

Rather than exporting the XDG variables globally, I created a wrapper script used only for Docker Sandboxes:

#!/usr/bin/env bash
set -euo pipefail

SBX_ROOT="/var/tmp/sbx-${UID}"

mkdir -p \
  "${SBX_ROOT}/config" \
  "${SBX_ROOT}/cache" \
  "${SBX_ROOT}/data" \
  "${SBX_ROOT}/state"

chmod 700 \
  "${SBX_ROOT}" \
  "${SBX_ROOT}/config" \
  "${SBX_ROOT}/cache" \
  "${SBX_ROOT}/data" \
  "${SBX_ROOT}/state"

export XDG_CONFIG_HOME="${SBX_ROOT}/config"
export XDG_CACHE_HOME="${SBX_ROOT}/cache"
export XDG_DATA_HOME="${SBX_ROOT}/data"
export XDG_STATE_HOME="${SBX_ROOT}/state"
export XDG_RUNTIME_DIR="/run/user/${UID}"

exec /usr/bin/sbx "$@"

Save it as:

/usr/local/bin/sbx-local

Then:

sudo chmod 755 /usr/local/bin/sbx-local

sbx-local diagnose
sbx-local login
sbx-local run codex

Is This a ZFS Bug?

Based on my testing, I can't conclude that Docker Sandboxes is incompatible with ZFS.

What I can say is:

• Docker Sandboxes v0.35.0 consistently failed when its XDG configuration and state directories were stored under my ZFS-backed home directory.
• The daemon itself appeared healthy.
• Moving the XDG configuration, cache, data, and state directories to a native Linux filesystem resolved the issue immediately.
• No packages or Docker configuration needed to change.

Final Thoughts

If you encounter:

ERROR: ensure daemon: daemon failed to start properly after 10 retries

while the daemon log reports:

api server started successfully

check where your XDG directories are located before reinstalling Docker or chasing permissions.

References

• XDG Base Directory Specification
  https://specifications.freedesktop.org/basedir-spec/latest/
• Docker Sandboxes Documentation
  https://docs.docker.com/ai/sandboxes/
• Docker Sandboxes Troubleshooting
  https://docs.docker.com/ai/sandboxes/troubleshooting/