shedix

Guide for agents

When something fails

What agents have hit while using shedix, and the fix for each: the key and link codes, network, SSH, machines that slept, sign-in on the machine, ports, installs, zsh, and handing off or forking Claude Code and Codex. Agents read the same text at /agents/troubleshooting.md.

Find what you see, then do what the row says. If nothing here fits, the error's own words usually say what's wrong: tell the person, quoting them.

Reaching shedix and the machine

You see Do
curl: (6) Could not resolve host Your sandbox blocks the network (Codex's does by default). Ask the person once for network access for the whole task, not per command.
401 The key is wrong or revoked. A saved key: remove it (python3 ~/.config/shedix/key.py forget) and get a new one with a link code; a pasted one: tell the person (agents.md, "The key").
403 The account isn't invited yet, or is suspended: tell the person.
key.py wait keeps saying it's still waiting The person hasn't approved yet: run it again until the code expires (10 minutes), then ask before starting a new one.
The person denied it. or The code expired. Tell the person; start a new link code only if they want one.
shedix answered 404 from key.py link This shedix doesn't have link codes yet: ask the person to paste a key from https://shedix.dev/profile#access (Tokens, New token).
402 or 409 from creating or starting Credit or a limit: https://shedix.dev/agents/reference.md, "Credit and limits".
ssh exits with 255, or connecting times out The machine stopped (it sleeps after an hour unused), or started again with a new IP. Look it up, start it if it's stopped, wait with ?wait=240, and write its SSH settings again (agents.md).
Permission denied (publickey) shedix's key isn't on the machine: add it with POST …/ssh-keys (agents.md, first step (a)).
<name> is not ready: … from the printer It's still booting: wait with ?wait=240.

Running things

You see Do
A command stopped after 2 minutes (Claude Code) Give it a longer timeout (up to 10 minutes) or run it in the background. Check tmux ls and the logs before running it again: the first run may still be going.
An install hangs It's waiting for an answer nobody can give in tmux: add < /dev/null so it fails at once, then use its non-interactive flag.
port … never opened Read the service's log (tail -n 40 ~/work/<session>.log): the service crashed or listens on another port (ss -Hltnp shows which).
A forward fails at once The port is taken on this computer: ask the person to stop the local app, or forward to another local port (-L 13000:localhost:3000).
zsh: no matches found or a path cut at a colon zsh: quote globs, and put braces round a variable before a colon (${NAME}:work/).
rsync: unrecognized option on macOS macOS's rsync is old: use only the flags in run-project.md.

Handing off or forking a session

You see Do
Codex on the machine shows "Trust this folder?" Add the project's folder to the machine's ~/.codex/config.toml, then start the session again (handoff-codex.md, step 3).
Claude Code on the machine asks for a theme or to trust the folder The person answers at https://shedix.dev/m/<machine>/claude?t=<tmux session>, which opens that session; don't answer the trust question yourself.
signed claude still says claude=off after the person signed in Give it a few seconds (the machine reports every couple of seconds) and poll again; if the sign-in page showed an error, send the person the #signin link again (agents.md, first step (b)).
duplicate session from tmux new A session by that name is already there (the person may have opened one on the page): use another name, like claude-handoff-2.
The person chose an option on a trust screen but nothing happened Those screens need the keyboard: the person presses Enter in the terminal (a tap on the text doesn't choose it).
no rollout found for thread id (Codex) The conversation's files aren't in ~/.codex/sessions on the machine with their dated folders: copy them as handoff-codex.md, step 2, says.
A sign-in screen in the session The agent isn't signed in on the machine: end the session, do the first step's sign-in check (b) with its #signin link, then start the session again.
The phone opens the laptop's conversation, not the machine's (Claude Code) The copy kept bridgeSessionId: copy it again without that field (handoff-claude-code.md, step 2).
The machine went to sleep while waiting for the person An agent waiting at a question isn't activity. Start the machine, then run the start step again.
A private file arrived that the person said no to Remove it on the machine (rm), tell the person, and check the copy used --exclude-from with the first step's list (paths start with /, relative to the project's folder).