termdeck
Any engine fix: The agent installs cleanly and the machine never appears online
An agent that installed without error and never appeared is almost never a network problem. It dialed out, it got an answer, and the answer was no. The log on that machine says which no it was.
Termdeck does not recognise this machine's token
Printed by Termdeck.
Diagnosis
A 401 on dial-in means the master does not recognise the token this machine is using. The usual history is that the machine was removed in the dashboard, or deleted and added again, which mints a new token and leaves the old one sitting in the file on disk.
A machine token belongs to one machine. Pasting the same install command on a second computer gives two agents one token, and the master keeps one and turns the other away rather than letting them evict each other in a loop.
That is a 402 rather than a 401. The agent is recognised and refused, it keeps retrying on a long backoff, and it reconnects on its own once the account has room again without anyone touching the box.
Check
| Run this | What a good answer looks like |
|---|---|
tail -n 40 ~/.termdeck/logs/agent.log | The agent writes both the refusal and the fix into its own log. Read the HTTP status: 401 is the token, 402 is the plan, and a connection error is neither of those and means the dial never landed. |
systemctl --user status termdeck-agent | On Linux, whether the service is running at all. A stopped unit looks identical in the dashboard and produces none of the log lines above. On macOS the equivalent is launchctl. |
grep TERMDECK_MASTER_URL ~/.termdeck/agent.env | Which master this machine dials. Never print the whole file: the token beside it is a password. |
Every command here has been run on a real machine. Termdeck answers the same questions for every machine you have connected, without opening a terminal on any of them.
Fix
Add machine issues a fresh token and writes it into agent.env. For a 401 that is the fix and the only one, because nothing on the machine can make an unrecognised token recognised.
Where two agents share one token, the second is turned away deliberately. Add that computer in the dashboard and install with the token it hands you.
Remove a machine you no longer use, or move up. The agent is already retrying and reconnects without being restarted.
Not this
That leaves a service running against a missing token, retrying forever, while the machine still holds its slot in the dashboard. Uninstall properly, or re-run the install.
The agent dials out, and the refusal it logged is proof the connection succeeded: a 401 can only come from the master. There is no inbound port to open.
FAQ
It means the token is wrong, not the account. A machine token is minted per machine, and removing or re-adding a machine in the dashboard replaces it.
Indefinitely, on a long backoff. It logs the reason loudly once and quietly after that, so the log carries the fix rather than thousands of copies of the symptom.
Add it in the new account and install with the token that account hands you. A token issued by one account is never valid for another.
If the log shows a 401 today, yes: something removed or replaced the machine in the dashboard. A machine that simply went quiet with no HTTP status in the log is a different problem.
Claude Code, Codex and Grok in one browser console