termdeck
Core concepts
Machines and fleet
Everything about a connected machine lives on one card 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.
Reading a machine card
| On the card | 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 version | The build running on that machine, next to the current build. |
| Platform | What the agent reported: macOS, Linux, or Windows. |
| Engines | Claude, Codex, and Grok, each as installed and signed in, installed and signed out, not installed, or could not check. |
| Last seen | When the agent was last connected, 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 and a colour so a fleet of five reads at a glance. 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 two warning badges
Both 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.
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.
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. |
| 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 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 Free, 2 on 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 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.