Troubleshooting

Find the section that matches what failed, and keep the visible error message handy. If the recovery steps don't help, contact support with that message and the project or thread where it happened.

Desktop looks stuck or out of date

If the titlebar shows Offline or Reconnecting, check your computer's network connection. Threads and machine status will catch up when the connection returns. For a view that remains stale, press Cmd+R to reload the desktop app.

If the full window stays on Checking sign-in… or Loading workspace…, choose Reload when the button appears after 15 seconds. This will reload the desktop app, just like Cmd+R.

If a reload fails, the desktop app will retry automatically. If the window stays on Still reloading boxes.dev…, choose Reload to start loading the app again. If it shows Can’t reach boxes.dev, check your connection and choose Retry now.

If you closed the main window, choose File → Show Workbench. If you're stuck on a page and can't return to the workbench, sign out and sign back in.

A devbox or Template box stops responding

If the desktop app responds but the selected machine doesn't, first confirm that you've selected the affected devbox or Template box. Then try these steps in order:

1. Click the CPU or memory meter. If a process is using excessive resources, stop that process from the process view.
2. If the machine still doesn't respond, choose Machine → Reset. This will stop shells, agent sessions, background commands, and user services while keeping your files.
3. If Reset fails, choose Machine → Reboot. Reboot will preserve files but stop every process, agent session, terminal, service, and connection on that machine.

Wait for a reboot to finish before starting another. If the result says the machine is sleeping, choose Wake. If the machine restarted but services aren't ready, wait briefly, then try Reset or contact support. See Sleep, wake, and recover for more recovery options.

Inspect Activity to see which processes are using the machine's resources. Select the image to enlarge it.

Setup scan, upload, or access failed

Return to your existing setup under Setups in progress in the desktop project menu. You can also choose Continue setup on its row in the setup wizard's Project step. If your local coding agent started the setup, choose View setup on its row instead, then see Set up a project with your local agent.

A scan missed something or stopped

Open the scan group with the missing items, describe what it should include, and choose Send feedback & rescan. Review the new findings before approving them. For a failed or stopped scan, use Retry scan.

If a scan is taking too long, choose Stop in its header. You can retry that scan later; stopping it will preserve other scans and completed reviews.

An upload or remote setup step failed

An interrupted upload will try to reconnect and resume automatically. If Retry upload appears, use it; confirmed uploaded parts will be kept.

For a temporary remote setup failure, use Retry setup when offered. If you stopped the setup agent yourself, choose Open setup thread and ask it to continue. Stopping the agent will leave setup paused until you continue the conversation.

If setup says boxes.dev ran into an unexpected error, retry setup. If it stops at the same step again, contact support with the project name and the step where setup stopped.

Git access failed

For local-folder setup, choose Fix Git access when offered. This will remove the incomplete Template box and return you to Finalize Bundle while keeping your approved review and bundle choices. Restore the named GitHub account's repository access, or choose SSH and register the displayed public key with your Git host before verifying it. You can also skip Git access and configure it after setup.

For Create from GitHub, follow the error's access action: reconnect the original GitHub account, grant the boxes.dev GitHub App access to the named repositories, or restore your write permission. An organization owner may need to approve the access request. Retry after access is restored. If repository policy requires SSH, cancel and restart this setup with Use an SSH key for GitHub pull/push access instead.

Use Rebuild bundle when setup asks you to prepare the upload again. If it returns to Git access, verify the displayed key before continuing.

Setup asks you to start over

Use the setup's start-over action if it says the saved setup can no longer be used. Your original folder on your computer will remain; boxes.dev will rebuild the pending setup and upload bundle. For a payment block, resolve the issue in Billing before retrying.

Member-project preparation needs attention

If a member project shows GitHub access needs review, choose Review GitHub access. Reconnect the intended account or grant the boxes.dev GitHub App access to every named repository, then retry. This project type requires that access; it won't switch to SSH or an older Team Template version.

For a saved environment or setup failure, open View details, choose Copy details, and send them to a team admin. Your unsent draft and attachments will remain available to retry after the problem is fixed. Existing devboxes remain usable. A startup script warning has a different recovery path, described below.

An optional MCP connection can show a warning without blocking your first thread. Follow that warning's sign-in or retry action. Required GitHub access and sign-in for the selected coding agent must be ready before work can start. See Maintain a Team Template.

A new devbox warns about its startup script

If a new devbox's thread warns that its startup script failed or timed out, the devbox still started; the warning describes that script run's result. Review the script's outcome before relying on it, then dismiss the warning. Dismissing acknowledges that exact result, and a different failure will warn again. The script is the project's Startup Script under Project settings → Devbox lifecycle.

In a Member project, the team script runs first with your connections and files available, followed by your project's script. Either failure will show a warning while the next script and agent continue; both results remain inspectable if both fail. For a team script, open or copy its details and contact a team admin. Admins can choose Review startup script to open its setting. Startup script failures won't pause other members' devbox creation.

A corrected script will apply to future devboxes. On this devbox, run the needed repair in Terminal or ask the agent; waking it or opening another thread won't rerun startup.

Codex, Claude, or an MCP needs sign-in

For a Codex or Claude sign-in error, use the thread's refresh action when offered. Otherwise, reconnect the affected account from Configure agents in the desktop app, or from the mobile app's Reconnect banner or Settings → Agent accounts. Check now will check the account without waking a machine. Needs re-auth means the provider rejected the saved login; an incomplete status check alone doesn't disconnect your account.

If Claude's browser sign-in page shows an error, retry on that page or cancel the attempt in boxes.dev and start again. You don't need to restart the desktop app.

To repair Codex sign-in from a terminal, run dvb setup --agents on your own computer. Don't run codex login or codex logout inside a Template box or devbox, or /login and /logout in Claude there; boxes.dev manages those sign-ins. After reconnecting, return to the thread and reply to continue.

A Claude account connected with Log in with Claude needs a new sign-in about every four weeks, and boxes.dev will remind you three days ahead. If Claude on a devbox doesn't have the skills, plugins, or connectors you use on claude.ai, open Configure agents and check that the active Claude account says claude.ai login. If it says Setup token, choose Switch to claude.ai login from its ⋯ menu. For connectors, also make sure Allow claude.ai connectors is selected. Then start a new Claude thread.

An MCP connection needs attention

If a slow MCP reconnection delays a message to an existing Claude thread in the desktop app, boxes.dev will keep the message queued and send it when Claude is ready, even after a wait of more than a minute. You don't need to send it again. For a sign-in error, follow the steps below.

Open Integrations → MCPs, then select the Codex or Claude button on the affected connection. If sign-in shows Status unknown, choose Retry status check to check the same attempt, or Cancel to start over.

For servers installed on the Template box, open Template-managed MCPs and choose Retry if the list won't load. This may wake the Template box. A dash in the server count means the list is unavailable; it doesn't mean no servers are installed. Member projects don't have this Template box inventory.

An older desktop version may offer a dvb mcp authorize command. Run it on your own computer, not inside a Template box or devbox.

An agent stopped before finishing

If a large Codex thread asks you to reload or update boxes.dev, press Cmd+R in the desktop app. Reloading won't stop the agent on the devbox. On mobile, open Settings → About → Release details and choose Check for update. If the message persists and no compatible update is available, install the latest app version or contact support.

If Retry says the thread is too large, send a new message to continue. The failed turn stays in your history.

If the message says an older thread is too large to reopen, start a new thread to continue. Updating the app does not remove this limitation for older threads.

Use the failure message to choose the next action:

• Model capacity: boxes.dev continues a Codex thread automatically after a short wait. If the message asks you to reply, wait briefly before continuing, or choose another available model.
• Temporary rate limit: wait briefly before continuing.
• Credits: add credits or wait for them to renew in your agent account.
• Sign-in: reconnect the affected agent account.
• Machine networking: continue after the machine can reach the agent provider.
• Internal, rejected-request, or execution errors: read the error details before continuing, and include them if you contact support.

After a Codex response fails, reply in the same thread to continue. Codex retains the message and attachments it received; you do not need to send them again. If it may already have changed files, ask it to inspect the current files before continuing. Retry for a message that has not been delivered is a separate recovery action.

For Claude, Resend is available only when boxes.dev can confirm that Claude never received the message. If delivery is uncertain, read the conversation before sending the request again. See Recover from a failed start or message.

A devbox will not start or wake

Read the failure message before retrying:

• If you've reached the awake devbox limit, sleep an idle devbox to make room. Sleeping won't delete it.
• If billing blocks compute, open Billing. A team admin may need to update payment, assign a paid seat, or add usage credits.
• If a snapshot or saved Team Template version is unavailable, follow the message's recovery action. Contact support if it offers no way to continue.

Waking can take many seconds or a few minutes. Wait for the attempt to finish. If it fails, the machine returns to Sleeping; use its wake control to retry. With auto-wake enabled, selecting the machine again after 15 minutes can also trigger one new attempt.

If repeated attempts fail and no billing or capacity block is shown, contact support with the project, devbox, and approximate time.

If moving a thread from the Template box failed, its menu may offer Move back to Template box. If a recovery notice says the machine was restored after an unexpected stop, inspect its files and Git status before continuing: changes made after the restored snapshot may be missing.

Billing or a plan limit blocks work

If you're not a team admin, send the billing message to an admin. Depending on the block, they may need to add a payment method, renew or change the plan, assign a paid seat, buy usage credits, or configure automatic credit reload. For a project limit, you'll need room for another project or a plan that allows more projects. For the available options, see Plans, seats, and box-hours.

Ports, files, or Git are missing

Select the devbox or Template box that contains the work and wake it if needed. Each devbox has separate files and services, so selecting another machine can show a different repository state or an empty ports menu. For a commit that shows the wrong name or email, go to A commit has the wrong author.

A port is missing or won't open

Wait for the selected machine to report its ports, then check that your development server is running on that machine. If an ordinary forwarded port can't open because your computer already uses that port, choose Use next available, or stop the local process using it. A stable Local URL keeps its exact port instead of offering another one: boxes.dev reports the conflict, and you can free the local port or turn off Local URLs for that devbox to return to ordinary forwarding.

GitHub rejects a fetch, pull, or push

Follow the error's recovery action to reconnect the original GitHub account, restore your write permission, or grant the boxes.dev GitHub App access to the repository.

If only pushes changing .github/workflows fail, choose Update GitHub access for each affected installation, then return to boxes.dev to check again. You can also use SSH. Ordinary Git operations can keep working while that additional permission is pending.

A commit has the wrong author

Open Account settings and inspect Git identity. Unless you saved an override, it uses your connected GitHub account's name and private no-reply email. Then run these commands in the affected repository to see which configuration file supplies the name and email:

git config --show-origin --get user.name
git config --show-origin --get user.email

Repository settings take precedence over machine-wide settings, which take precedence over the Account identity. Change the setting at the scope you intend: Account for your shared default, git config --global for this machine, or git config --local for this repository.

If Account reports a failed update for a saved override, choose Retry. GitHub defaults retry automatically. Active machines will update; sleeping machines will catch up when they next wake. If Git reports an invalid configuration file, repair the named file; changing the Account identity won't fix it.

GitHub CLI authentication failed

Wake the affected machine, then open Integrations → GitHub. If you want gh to use your connected boxes.dev GitHub account, turn on GitHub CLI in devboxes. GitHub can be connected while this setting is off — desktop setup offers the choice separately — so check the switch even when pull and push already work. Complete any reconnect or machine update the page requests.

Without personal access, use Manage repository access to check that your GitHub account and the boxes.dev GitHub App can reach every known repository in the project. To use your personal permissions, run gh auth login or connect optional personal access in Integrations. Approve with the GitHub account connected to boxes.dev. Managed gh will prefer personal access; GitHub will enforce your permissions on each command.

Manage disconnects through boxes.dev. When the setting is off or GitHub isn't connected, gh uses credentials configured on the machine, including native gh auth login behavior.

The GitHub CLI access setting is separate from automatic Git fetch, pull, and push access.

A GitHub CLI command is denied

If a gh command fails with HTTP 403: Resource not accessible by integration, it ran with the boxes.dev GitHub App's access, and the App doesn't have the permission that command needs.

For supported commands that need a newly requested permission, managed gh will show a link to the affected account's permission review. Send that link to an installation owner, ask them to accept the update, then retry your command. Email access needs your own Update connection approval instead; gh will link to Account settings for that step. If no link appears, use the steps below.

For an Actions command, ask the repository's installation owner to approve Actions read and write in GitHub Settings → GitHub Apps → boxes.dev, then retry. Existing installations keep read-only Actions access until their owner approves the increase. Approved App access can start, rerun, and cancel workflows and manage their runs, logs, and artifacts. Actions writes, including gh workflow run, gh run rerun, and gh run cancel, will show the relevant approval link before running when an update is needed. GitHub will still show its original error if the command is denied.

For issue changes or publishing check results, ask the installation owner to approve Issues and Checks read and write, then retry. The App also requests read-only access to deployments and organization members. Reading your account's email addresses requires your own approval of the updated GitHub authorization; choose Update connection in Account or Integrations → GitHub to review and approve it.

If personal access is connected, gh prefers it. Personal access has different permissions: the scopes requested by boxes.dev do not include account email access, and personal access cannot publish check runs. Choose Disconnect personal access to use the App for those commands after approving its required permissions. For other commands beyond the App's access, optional personal access may provide the permission you need.

To let gh use your own GitHub permissions, connect optional personal access:

1. Open Integrations → GitHub or Account settings.
2. Under Full GitHub CLI access (optional), choose Enable.
3. Copy the one-time code, then approve the official GitHub CLI on GitHub with the GitHub account connected to boxes.dev.

You can also run gh auth login in a Template box or devbox, or ask your agent to run it. The command will show a one-time code and approval URL, then wait for your approval.

After you approve, gh will use your personal access on all of your Template boxes and devboxes. Retry the command that failed.

Personal access can't do more than your GitHub account is allowed to do in that repository. If Integrations warns that personal access can't reach a repository, choose GitHub permissions to authorize the official GitHub CLI for that organization, then choose Check again.

Automations, Slack, or Linear did not start work

For a saved automation, open it and inspect its recent runs. If a run hit the awake devbox limit, sleep an idle devbox or reduce the number of simultaneous runs. For a billing block, resolve the issue in Billing. After fixing the cause, retry through the original trigger, or choose Run now if it is available. For work that should have started from Slack or Linear, start with that integration's section below.

Separate Slack requests and Linear assignments can start work at the same time, so a burst of requests can exhaust available devbox capacity.

Slack

Open Team Settings → Slack to check the workspace connection. If it's missing, revoked, or lacks required permissions, ask a team admin to connect or reinstall the integration.

If Slack says your account isn't linked, send connect to the @boxes.dev app in Slack. For a missing channel, add the app to that channel, then choose Recheck in Team Settings. Confirm that the automation is active and permits that channel and user.

For missing attachments, check that the file is still available in Slack and the bot can access its channel. Slack file import also has size and sender restrictions; see Slack.

Linear

Open Team Settings → Linear and choose Check. If access was revoked, permissions changed, or the connection remains invalid, a team admin needs to reconnect Linear. For the full setup steps, see Linear.

If new assignments don't start work, link your Linear identity in Account settings and confirm that your default assignment automation is active. Existing issues can continue their threads, but new assignments require both a working workspace connection and your linked identity.