Troubleshooting
Check one layer at a time: the service, then your connection, then Claude, then Git. Keep the SSH tunnel from Getting started working while you diagnose anything else.
Two commands answer most questions:
SHELL
npm run doctor -- --service # tools, resources and the running service
tmux capture-pane -p -S -200 -t =ccr-cloud: # the control plane's recent output#Setup and the service
| Symptom | What to do |
|---|---|
| Setup reports a missing tool | Install it for the service user, then run setup again. |
--start can't verify the API | Read the control plane output (above). Check the port in server.env and look for an old process on it: ss -ltnp 'sport = :8787'. |
| Setup says Claude isn't found | Make sure claude is on the PATH of the shell that runs setup. |
| Host is slow or tasks die | Run npm run resources and run fewer tasks at once. See Check host resources. |
#Connecting
| Symptom | What to do |
|---|---|
The browser can't reach localhost:8787 | Keep the laptop SSH tunnel running, and check you opened the same local port. |
| The token is rejected | Read the token from the same server and data directory as the address you opened. Each ccr-cloud instance has its own token. |
| HTTPS address doesn't load | Check the service and your connection process (Tailscale Serve or the Cloudflare tunnel) separately. Both must be running. |
| Phone works only on some networks | Check Tailscale or Cloudflare reachability on that network. Use the laptop tunnel meanwhile. |
#Claude
| Symptom | What to do |
|---|---|
| A scratch task fails or never replies | First check the task's status and any pending approval. Then, on the server as the service user, run claude and complete login, or test model access with claude -p "Reply OK". |
| It worked before, now fails to authenticate | Renew the login through Claude Code as the same user. Check CLAUDE_CONFIG_DIR if you use a custom one. |
| Task details | Read DATA_DIR/host/SESSION_ID/runner.log. |
GitHub checks and network probes don't test model access. The scratch task is the end-to-end check.
#Repositories
| Symptom | What to do |
|---|---|
| "Repository not found" when adding a URL | Use an SSH URL for an SSH key, or HTTPS for a credential helper. Then run npm run github -- --repo URL on the server. Failed checks show a diagnostic ID; find it in the control plane output. |
| A checkout is missing from Repositories on this server | Select Rescan repositories. Check that CCR_CLOUD_REPO_ROOTS uses absolute paths, and that the checkout is within three levels and not behind a symlinked folder. |
| A task can't start in a new repository | Make an initial commit first. |
| Cloning works in your shell but not in tasks | Your SSH agent may have been forwarded from your laptop. Use credentials that stay on the server. |
#The app and server don't match
If Server setup is unavailable, project routes return not found, or a new feature is missing after an update, the browser has new files but an older control plane is still running. Pulling code doesn't reload it.
SHELL
curl -s http://127.0.0.1:8787/api/health # current versions include "apiVersion": 2Restart the service, then refresh the browser.
#Still stuck?
Open an issue with the steps to reproduce. Leave out tokens, server.env and private logs.