Troubleshooting
Start with loadshift doctor
It checks SSH, the file sync, port forwarding and whether you're inside your workspace folder, and says how to fix each failure.
Commands run on my computer instead of the machine
Start your agent with loadshift claude, loadshift codex or loadshift opencode, not on its own, from inside the project. Only commands inside that project go to the machine. With Codex, also check that you trusted the loadshift hook in Codex's /hooks: until you do, Codex runs commands on your computer.
The machine is stuck on Booting
First boot installs packages and takes 1–2 minutes. After 20 minutes it's marked as needing attention; delete it and create a new one, and tell us if it happens twice.
Private packages won't install on the machine
The machine has no credentials of its own. Private npm packages work by themselves when your .npmrc gives the scope a registry and your computer has the token: npm on the machine goes through a proxy on your computer, which adds the token, so it never leaves your computer. This needs Node on your computer; loadshift doctor checks it. For packages under an npm org on the public registry, list the scope in LOADSHIFT_NPM_SCOPES="@yourorg". For other tools that read a token from the environment, add LOADSHIFT_PASS_ENV="NPM_TOKEN" to ~/.loadshift/config: loadshift gives that variable to each command there without saving it on the machine. For git+ssh dependencies, add LOADSHIFT_FORWARD_AGENT="1", so commands use your computer's SSH agent. Then start your agent again; loadshift doctor shows what's passed.
Permission denied (publickey)
Your key isn't on your account. Run loadshift login again, which adds it, or add it under SSH keys in the dashboard.
Host key verification failed
The machine was recreated with the same name. Run loadshift connect NAME again to pin its new keys.
Files aren't syncing, so the command wasn't run
The connection dropped, usually after your laptop slept or changed Wi-Fi. loadshift up reconnects and catches up; loadshift status shows the sync's state. Commands refuse to run on the machine while its files might be out of date.
Something is missing on the machine
.git, dependency folders like node_modules, and anything git ignores (except .env files) aren't synced. Have Claude install dependencies (npm install and so on), which runs on the machine. git and gh run on your computer.
loadshift says the folder is still mounted
You used an older version, which which mounted the folder. Run sudo umount -f on that folder, then loadshift connect.
localhost:PORT doesn't load
Check the server is listening on the machine (loadshift ssh, then ss -ltn). It must listen on 127.0.0.1 or 0.0.0.0. loadshift status lists current forwards.
Claude uses macOS-only commands
Make sure you started it through loadshift (loadshift claude): it tells the agent the shell is Linux.
On Windows (WSL2)
Install loadshift and your agent inside WSL, not in Windows: loadshift refuses an agent it finds on Windows' side of the PATH (under /mnt/c). Keep projects in WSL's own folders (such as ~/code): under /mnt/c they work, but git and the sync are much slower. loadshift login opens your Windows browser with wslview or explorer.exe; if neither works, open the link it prints. Dev servers forwarded to WSL's localhost open in your Windows browser too. Docker Desktop keeps logins in Windows: to use one on the machine, add <registry>=desktop.exe to LOADSHIFT_CREDENTIALS.
The browser didn't open on Linux
loadshift login opens it with xdg-open only when there's a desktop session. Over SSH, or without a desktop, open the link it prints on any device and approve the code there.