Skip to content
d_devboxby 508.dev/ DocumentationDashboard ↗
Browse documentation
DOCUMENTATION / Troubleshooting

Troubleshooting

Start with the narrowest failing boundary: client installation, SSH identity, workspace inventory, vendor tool or preview.

The client command is not found

Confirm Node.js 24+ is active and add the installer's printed bin directory to PATH. The default is ~/.local/bin. The installer does not edit shell profiles automatically.

If your version manager removed the Node executable used by the launcher, activate Node.js 24+ and reinstall. An unrelated existing devbox launcher is never overwritten automatically.

A download returns 404 or fails integrity

Fetch a fresh /install.sh from your trusted deployment. An old copy can reference a content-addressed release no longer served after a rollout. Do not disable checksum validation or switch to an untrusted mirror.

SSH works manually but Devbox refuses

Compare the saved machine/account with the alias you used. Devbox requires the pinned Ed25519 host identity and intentionally disables implicit credential forwarding. Check custom IdentityFile/ProxyJump settings without weakening host-key checks.

A host rebuild may legitimately change identity; verify it independently before changing saved trust. Do not automatically retry another machine on identity mismatch.

Workspace inventory is partial or stale

TERMINAL
devbox workspace refresh --computer home
devbox workspace list --computer home --json

Check approved roots and Git worktree health on the host. A failed scan does not prove a tree was deleted. If a currently observed tree is known, use open --workspace <id>; it still validates path, origin and HEAD.

A plain SSH or older host may lack remote-workspace inventory. The canonical prepare/reuse fallback remains available. Install the operator-signed current daemon/helper for native discovery; never substitute an unsigned helper just to clear the warning.

Setup refuses an existing workspace

The remote tree may have diverged or contain new work. Open it and inspect its state. Do not reset, delete or clean the tree as a connection repair. Resolve Git history deliberately.

An agent command is missing

Install the tool in the remote account. Ensure its supported user-local path or selected mise/nvm runtime is available. Authenticate on the host, and complete vendor trust prompts interactively. Existing conversations are not automatically migrated between clients.

A preview does not load

Confirm the app is running on the remote port, then use an explicit port to separate discovery from forwarding. Check the local port is free and the forwarding command is still running.

For HMR, verify the framework's forwarded origin, allowed hosts and WebSocket port. Do not disable all host checks. Browser gateway previews are disabled in the current test deployment.

Enrollment cannot proceed

The operator must supply a signed manifest and an independently trusted key. Check Python archive filtering, Linux x86-64 release compatibility, disk space, Ed25519 SSH host key, systemd user manager and lingering.

Browser approval, installation and heartbeat are separate stages. A request being accepted does not prove the daemon is online. Preserve the typed error and consult the operator rather than bypassing signature or identity checks.

Development machines. Your code. Your control.
Private pilot · Feature availability is called out in each guide.