termdeck
Core concepts
Machines and fleet
Every connected machine is one row of the list in Settings, then Machines & accounts: whether it is online, what it can run, and what is wrong with it. Click a row to open that machine's own page, where you fix it without a support ticket.
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. A CLI that is not installed has an Install button on the machine's page. |
| 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. |
To connect another machine, use Add machine beside the list's heading. On a phone the row keeps only the name and the dot; the rest is on the machine's page.
A machine's page
Clicking a row opens the machine's page. Its address names that machine, so you can bookmark it or send it to yourself, and your browser's Back button, or Back at the top, returns to the list. Under the machine's name and status, the page has these sections, top to bottom:
| Section | What you do there |
|---|---|
| Coding agents | See each CLI's version and sign-in state. Install a missing one, and Recheck after you change something on the machine. |
| Accounts | Show the Claude or ChatGPT logins saved on the machine, then add, check, switch or remove them. See Accounts. |
| Health | The verdict and every check, with Run checks again. |
| Configuration | Show the settings files, hooks, sub-agents, skills, commands and plugins on the machine, read-only, and Open Extensions to switch them on or off. |
| Manage | Update agent, View logs, Edit the name and colour, and Regenerate token. |
| Remove machine | Alone at the bottom, and it asks before it does anything. |
A warning about how the agent survives a logout or a restart sits above all of them, with the command to fix it.
In View logs, every start of the agent says how the run before it ended: stopped on purpose (an update, say), ended because the machine restarted, crashed (the error and its stack are just above), or died while the machine stayed up, which means something stopped it from outside.
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 page: 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 row and page. 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.
Health checks
The Health section of every machine's page runs the checks when you open it, and Run checks again repeats them. 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. |
The Configuration section links to Extensions for that machine, where you can see every MCP server, plugin and skill on it and turn each one off or on.
Reading the agent log
View logs, under Manage on the machine's page, fetches 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 machine's page shows Update agent under Manage 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, under Manage on the machine's page, 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
Remove machine, at the bottom of the machine's page, asks first, then revokes its token, takes it off your list and returns you to the 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 Free and Starter, 10 on Pro. 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 its row 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.
A Mac keeps itself awake while a chat is running on it, so a long turn is not cut off when you walk away. Once nothing is running it sleeps as usual. Closing the lid still puts it to sleep, and a turn running then stops until it wakes. A sleeping Mac also wakes briefly about once an hour for its own housekeeping, so its row can show online for a minute and then offline again. That is the Mac, not a fault.
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.