Skip to content
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
Browse docs

Help

Troubleshooting

Resolve common Docker, build, token, gateway, network, session, and export failures.

On this page+

Docker is unreachable

If the launcher or image listing reports a Docker connection error, verify the daemon from the same shell and inspect DOCKER_HOST. The provider uses the Docker Engine API and honors that endpoint.

Shell
docker info
printf '%s\n' "${DOCKER_HOST:-<default Docker endpoint>}"
sandbox-manager-cli list_docker_images

Start Docker Desktop or the system daemon, then rerun image listing before attempting sandbox creation.

Gateway will not start

Run the launcher in the foreground long enough to read its explicit error. It builds host binaries, verifies the packaged daemon, checks both Git toolchain archives, and only then starts the background gateway.

Shell
start-sandbox-docker-gateway --rebuild-binary
tail -n 100 "${SANDBOX_GATEWAY_LOG:-/tmp/eos-gateway.log}"

A missing dist/sandbox-daemon-linux-* artifact can be repaired with cargo run -p xtask -- package. If dist/git/linux-arm64.tar or dist/git/linux-amd64.tar is missing, stop: the repository currently has no documented source-owned generation command for those archives.

Clients cannot authenticate

Repository wrappers read the private token file and export the credential. Confirm the file path and use the wrappers from bin; do not copy the token into YAML or browser code.

Shell
export PATH="$PWD/bin:$PATH"
sandbox-gateway-token path
ls -l "$(sandbox-gateway-token path)"
sandbox-manager-cli list_sandboxes

If you intentionally set SANDBOX_GATEWAY_AUTH_TOKEN, it must match the configured token file. Also confirm that SANDBOX_GATEWAY_SOCKET names the same gateway that created that token.

Sandbox creation fails

Verify the image reference and workspace through the same public discovery operations used by the console. A configured manager.workspace_roots allowlist rejects roots outside its absolute entries.

Shell
sandbox-manager-cli list_docker_images
sandbox-manager-cli list_workspace_directories
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /absolute/workspace

If creation leaves a record, inspect it before destroying it. The lifecycle state and error are more useful than retrying blindly.

Shell
sandbox-manager-cli list_sandboxes
sandbox-manager-cli inspect_sandbox --sandbox-id eos-abc
sandbox-manager-cli destroy_sandbox --sandbox-id eos-abc

Commands or network fail

First separate shell failure from connectivity. Run a local command, then inspect the sandbox snapshot and recent domain events. The checked production config permits RFC1918 egress and injects Docker Desktop HTTP proxy variables; a local override may replace either policy.

Shell
sandbox-runtime-cli --sandbox-id eos-abc exec_command "id && pwd"
sandbox-observability-cli snapshot --sandbox-id eos-abc
sandbox-observability-cli events --sandbox-id eos-abc --last-n 30

Commands cannot see paths masked by runner.mount_mask.hidden_paths; /eos is hidden in the baseline. Review Configuration before changing network or mount policy.

Sessions or publication stall

Use observability instead of internal lifecycle routes. The last trace shows operation timing, while LayerStack and cgroup queries expose leases, bookings, disk use, and resource pressure.

Shell
sandbox-observability-cli trace --sandbox-id eos-abc --trace-id last
sandbox-observability-cli layerstack --sandbox-id eos-abc --window-ms 60000
sandbox-observability-cli cgroup --sandbox-id eos-abc --window-ms 60000

A publication conflict rejects the candidate rather than overwriting newer durable state. Read the latest snapshot and rerun the intended change from a fresh automatic session; see Capture and conflicts.

Export fails

The destination must be absolute. Directory format applies the delta into a directory; tar and tar-zst expect archive paths. Only published layers are exported.

Shell
sandbox-manager-cli export_changes --sandbox-id eos-abc --dest /tmp/sandbox-delta.tar --format tar

If expected files are absent, verify them with file_read before export. Do not call internal LayerStack export or chunk operations directly.

Console will not open

Start the supported stack, then check the loopback catalog and the console log. The default listener is 127.0.0.1:7880 and the default log is /tmp/eos-console.log.

Shell
start-sandbox-console-stack
curl --fail http://127.0.0.1:7880/api/catalog
tail -n 100 "${SANDBOX_CONSOLE_LOG:-/tmp/eos-console.log}"

A 401 or 502 from an API route usually means the console and gateway disagree about the endpoint or token. A 404 from a direct daemon path may be correct: only health, preview forwarding, and POST /files/list are in the daemon HTTP allowlist. See the daemon HTTP boundary.

58 results