Troubleshooting Sessionboxer: Docker, certificates, macOS

• "docker: permission denied" when starting: add your user to the docker group (sudo usermod -aG docker $USER, then log out and in).
• Session goes to error with "cannot pull ghcr.io/…": the Sandbox image for this version is still downloading (watch the Control Plane log) or the machine cannot reach ghcr.io; npm run build:image builds it locally instead. "sandbox image … not found; run npm run build:image" appears only with a custom SESSIONBOXER_IMAGE.
• "method not found: _sessionboxer/…" after updating Sessionboxer: the box still runs the previous version's internals. Stop and Resume the session; the current build is copied into the box on every start, so npm run build:image is only needed when the image itself changes (system packages, agent CLIs).
• Code pane says "openvscode-server is not installed in this Sandbox image": run npm run build:image, then Stop → Resume the session.
• Devin session fails right after creation: Devin occasionally times out while loading team settings on a cold start. Sessionboxer retries a few times; if it still fails, Resume the session.
• cannot fetch https://github.com/…: self-signed certificate in certificate chain in the Control Plane log (downloading frpc, cloudflared or gh): the same proxy, and the Control Plane did not find its CA — see Global settings → Environment → TLS certificates, paste the PEM there (applies at once, no restart), or put the binary in ~/.sessionboxer/bin/ yourself.
• "self signed certificate in certificate chain" from an MCP server or the agent inside a box: your machine goes through a TLS-inspecting proxy (Cloudflare WARP, Zscaler…). Check Global settings → Environment → TLS certificates lists its CA (paste the PEM there if not), then Stop → Resume the session. The same error from curl or npm during npm run build:image means that CA was not found on this machine: build:image prints the ones it uses; paste the PEM in that Settings section and build again.
• Docker inside the box can't pull images: Docker Hub rate-limits anonymous pulls per IP; log in with docker login in the box's Terminal or pull from another registry.
• "No route to host" / "Host is unreachable" for a private address from a Docker-enabled session while public sites work and your machine reaches it: the address falls inside a network the box's own Docker daemon owns (192.168.240.0/20 by default, 172.17.0.0/16 when the setting is empty). Check with docker exec sbx-<session id> docker network inspect bridge -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}' (and docker network ls inside the box for compose networks), then set Global settings → Addresses for Docker inside Sandboxes to a block outside anything you reach and create the session again — see Docker inside sessions. If the outer sessionboxer network overlaps instead (docker network inspect sessionboxer), move Docker's own pools in /etc/docker/daemon.json (bip, default-address-pools) and restart Docker. A reply that gets as far as certificate verify failed is not this problem but the CA one above. With Cloudflare WARP on Linux, Cloudflare also documents lowering the Docker bridge MTU (1500 → 1420) when large transfers hang.

macOS

Sessionboxer talks to each box over the private sessionboxer Docker network. On macOS the Docker daemon runs in a VM, and only OrbStack routes container addresses to the host. Sessionboxer checks which daemon it is talking to at startup (the sandbox reach: ip|localhost line in the log):

• OrbStack: boxes are reached by container address, exactly as on Linux.
• Docker Desktop, Colima, …: each box additionally publishes its two internal ports (daemon and desktop) on 127.0.0.1 with random host ports, and the server dials those. Nothing is exposed beyond your machine. SESSIONBOXER_SANDBOX_REACH=ip or =localhost overrides the detection (for example ip with Docker Desktop + docker-mac-net-connect).

Other notes: Colima does not create /var/run/docker.sock, so export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock before npm start. Sysbox is Linux-only, so Docker inside the Sandbox always uses the privileged mode on macOS (the box is still inside the Docker VM, not your Mac). The sandbox image builds natively on Apple Silicon (arm64).