Troubleshooting

Use this page to narrow down common failures before escalating.

Sandbox is stuck setting up

Open setup logs and look for the first failing command. Bootstrap failures are usually caused by missing credentials, GitHub access problems, or a transient package install failure.

Agent stays on working

Check whether the sandbox bridge is still producing events. If callbacks cannot reach the local worker, the app may still recover events by polling bridge logs.

Preview URL does not load

Confirm the process is listening on the expected port and bound to 0.0.0.0. Then request the service from inside the sandbox before checking the forwarded preview URL.

Terminal does not connect

Refresh the terminal tab and check the sandbox status. Sleeping sandboxes need to wake before a terminal can attach.

Docs search has stale results

Rebuild the docs site. The search index is generated at build time from Markdown source files:

npm run build:docs

If the source file is not listed in docs/docs.json, it will not appear in navigation or search.