termdeck
Core concepts
Machines and fleet
Every connected machine is one row of the table in Settings, then Machines and accounts: whether it is online, what it can run, what is wrong with it, and how to fix that without a support ticket. Click a row to open its details.
Setting this up for the first time? Manage Claude Code on multiple machines walks through it in order, start to finish.
Reading a machine row
| In the row | What it tells you |
|---|---|
| Green dot | The agent has a live connection right now. Grey means the machine is asleep, off, or without network. |
| Agent | The build running on that machine. It turns amber when a newer build is waiting. |
| Platform | What the agent reported: macOS, Linux, or Windows. |
| Coding CLIs | The Claude, Codex, and Grok marks. A full-colour mark is ready, an amber dot means it needs a sign-in, a grey dot means the machine could not say, and a faded mark is not installed. Open the row for the account and the fix. |
| Last seen | How long ago the agent was last connected, such as 3h ago, for a machine that is offline now. |
| Warning badge | Present only when something will bite later. See the next section. |
Give machines a display name, an icon and a colour so a fleet of five reads at a glance. Choose them when you connect a machine, or later from Edit on its card: pick one of eight icons (server, desktop, laptop, cloud, chip, terminal, container, globe) and one of eight colours, and the preview shows the mark as it will appear. That mark then stands next to the machine's name everywhere Termdeck shows it: the sidebar rows, the chat hover card, the Home board, the machine picker on the new chat page, Usage, the approvals log, Settings, then Projects, and the machine's own card. The machine key, the short name used in routes and in local settings, is separate from the display name and can also be changed. Renaming the key moves the settings keyed on it with you.
The warning badges
The first two mean "this machine will stop being here, and here is when". They only appear when the agent itself reports that state, so they never speak for a machine that cannot answer. The third is about right now.
Stops at logout
The agent runs as a systemd user service and lingering is off for your account, so systemd shuts it down the moment you log out of that machine. Run this once on the machine:
sudo loginctl enable-linger $USERThe installer tries to do this for you and only fails when sudo needs a password it cannot prompt for, which is the normal case for curl | sh.
Two agents
Two agent processes are connected with this machine's token. Termdeck keeps the one that arrived first and turns the other away, so the machine still works, but the one being turned away keeps trying and you are running an agent you did not mean to.
It is almost always the install command pasted on a second computer. A token belongs to one machine: to connect another, use Add machine and give that one its own. Two agents on the same computer no longer cause it: a second one waits without connecting, and re-running the install command replaces the running agent rather than adding another.
Stop whichever process you do not want. The badge clears itself once the extra agent gives up, which takes a few minutes.
Stops at restart
Nothing on the machine is registered to start the agent again. Either it was started by hand instead of being installed, or the installer could not register a service, which happens on Windows when Task Scheduler denies access.
Rerun the installer, on Windows from an elevated PowerShell, and it registers properly.
Run checks
Every card has a Run checks action. It gathers what the machine reports and turns it into a verdict with one row per check, worst first. Two rules make the report trustworthy:
- It never says a thing is fine when it could not read it. A check with a missing input reports "could not tell" instead.
- Every row that is not green carries a fix, written as a command or an exact place to click. A red row with no next step is a support ticket with extra steps.
What it looks at:
| Check | What it catches |
|---|---|
| Connection | The agent is not connected right now. |
| Agent version | The machine is behind the current build. A warning, not a fault: agents update themselves. |
| Engine installed | None of the three CLIs was found. Names the executable variables for unusual install locations. |
| Engine login | A CLI is installed but has no usable login, so it cannot start a chat. Names the exact login command. It reads as expired instead when a login is saved and the provider refused it, which is a different fix: refresh the one you have rather than make a new one. |
| Model catalog | The CLI refused to list models, with its own reason attached. This is the answer to an empty model picker. |
| Settings files | A CLI settings file that does not parse. High value: the engine silently ignores such a file, so every permission, hook, and variable in it is inactive while you believe it is in force. |
| Blocking hooks | Lists any PreToolUse hooks that are armed. Not a problem, but the most common reason a tool call simply does not happen. |
| Projects | You have not added any folders, so chats will not appear in your sidebar. |
Reading the agent log
The card can fetch the agent's own log without you opening a terminal. It covers connections, restarts, updates, rollbacks, and errors. On disk it is at ~/.termdeck/logs/agent.log, and on Windows a crash that happens before the agent's own handler runs is appended to agent-crash.log in the same folder.
Updating an agent
Agents update themselves when the master ships a new build. The card shows an Update action whenever the machine's version differs from the current one, and a machine sitting a version behind for a few minutes after a release is normal rather than broken.
If an update goes wrong, the machine recovers on its own. A build that crash loops or that runs but can never connect is rolled back automatically and quarantined so the same one is not taken twice. Only when that fails as well do you need the repair command, and the dashboard offers it at that point rather than before.
Regenerating a machine token
Use Regenerate token when you have lost the original, when you are reinstalling, or when you are moving a machine name to new hardware. The master disconnects the old agent the instant the old token stops being valid, so nothing is left running under a credential you have retired.
Regenerating drops you back into step two of the connect wizard with the new command ready to copy. Everything else about the machine, including its name, its icon, its colour, and every chat that references it, is untouched.
Removing a machine
Removing a machine from the dashboard revokes its token and takes it off your list. It does not touch the machine itself, so run the uninstall command there as well if you want the agent gone.
Your transcripts are unaffected either way. They belong to the coding CLIs and stay on the machine's disk.
Device limits
Each plan allows a number of connected machines: 1 on Starter, 10 on Pro. An account with no plan cannot connect any. Agents over the limit are refused at connection time, which happens in a terminal nobody is watching, so the dashboard says so too and marks exactly which machines are affected.
Nothing is deleted when you go over. Remove a machine you no longer use, or move to a plan with more room. Fleets larger than 10 are available by arrangement at [email protected].
A machine that is offline
An offline machine is usually a machine that is asleep, off, or without network, and that is not something to fix. What matters is whether it comes back on its own. Work through this in order:
- Is the machine awake and online? Sleep is the most common answer by a wide margin.
- Does the card carry a warning badge? Then it went down at a logout or a restart and needs the fix above.
- Is the service running?
systemctl --user status termdeck-agent,launchctl list | grep termdeck, orGet-ScheduledTask -TaskName TermdeckAgent. - Can the machine reach Termdeck?
curl -fsSL https://termdeck.io/VERSION. - Still nothing? Run the repair command. It reuses the token already on the machine, so there is nothing to look up.
Troubleshooting has the same list with the failure modes spelled out.
A machine that is still catching up
Right after a machine connects, and again after a Termdeck update, that machine has to read its chat history before its chats can be listed. While it does, the sidebar and the board show it as catching up rather than offline, and the chats on your other machines appear straight away instead of waiting for it. There is nothing to do: the list fills in on its own once the machine has finished, usually within a few seconds. A machine that stays on catching up for minutes is connected but slow to answer, and a laptop on a weak connection is the usual reason.