termdeck
Open Termdeck

Get started

Install the agent

One command per machine. This page covers what that command actually does, how each platform keeps the agent alive, and every way to update, repair, or remove it.

Requirements

  • Node.js 18 or newer, with npm on the path. Check with node --version.
  • Outbound HTTPS to termdeck.io. The agent dials out and keeps one WebSocket open. Nothing listens for inbound connections, so there is no port to open and no tunnel to configure.
  • curl on macOS and Linux. It ships with both.
  • A user account you can log in as. The agent runs as you, not as root, and it needs your permissions to read your repositories.

Windows Server, headless Linux, and a Mac that mostly sleeps all work. A sleeping machine simply shows as offline until it wakes.

Get your install command

The command carries a token that identifies one machine, so it comes from the dashboard rather than from this page. Open Settings, then Machines and accounts, choose Add machine, name it, and copy what the wizard prints.

Machine names are lowercase letters, digits, and dashes, up to 32 characters. The name is part of every URL that addresses that machine, so pick something you will recognise in a list.

Terminal
curl -fsSL https://termdeck.io/install.sh | TERMDECK_AGENT_TOKEN=agt_your_token sh

The token is a machine credential, not an account password. It authorises one agent to connect as one machine on your account. Anyone holding it can register a machine under your name, so treat it like an SSH key and do not paste it into a shared channel.

Reading the source before you run it

Piping a script from the internet into a shell is a reasonable thing to be suspicious about. The installer takes that seriously and asks, before it touches anything:

Prompt
Read the agent source before installing? [y/N]

Answering y prints the installer and every agent file it is about to download, in full, then asks again before continuing. The whole agent is a handful of small files, so this is a readable amount of code rather than a gesture.

If you would rather read it out of band first, fetch the same URLs by hand:

Terminal
curl -fsSL https://termdeck.io/install.sh | less
curl -fsSL https://termdeck.io/download/agent/manifest.json
curl -fsSL https://termdeck.io/download/agent/capabilities.js | less

capabilities.js is the file worth reading closely. It is the complete list of things the agent will ever do on your machine. Nothing outside that list is reachable, however the request is phrased. See Security and privacy.

What the installer does

  1. Checks its prerequisites

    Node, npm, and curl. If any is missing it stops and says which, rather than failing halfway through.

  2. Asks the master which files this agent version needs

    The file list comes from /download/agent/manifest.json rather than being hardcoded, so a new agent never lands missing one of its own dependencies.

  3. Downloads the agent

    Into ~/.termdeck/agent. This is the thin agent only, not the Termdeck codebase.

  4. Installs two dependencies

    ws for the WebSocket and chokidar for watching transcript folders. That is the entire dependency tree.

  5. Saves the token

    To ~/.termdeck/agent.env with mode 600 on macOS and Linux. On Windows the token goes into a scheduled task wrapper under your profile.

  6. Registers a background service

    Whichever supervisor the platform provides. The next section is the detail, because this is the step that decides whether your machine is still online tomorrow.

  7. Reports what it found

    Including a warning if Claude Code or Codex is not installed, and a loud warning if it could not register a service that survives a restart.

How each platform keeps it running

An installer that says "done" in green while quietly leaving a process that dies at the next logout is worse than one that fails. Termdeck reports which of these actually happened, both in the terminal and on the machine card in the dashboard.

Linux with systemd

A user unit is written to ~/.config/systemd/user/termdeck-agent.service and enabled. Restart policy is always with a 3 second delay.

Systemd shuts your user services down when you log out, unless lingering is enabled for your account. The installer tries to enable it for you with a non interactive sudo. If sudo wants a password it cannot prompt for under curl | sh, it says so, and the machine card in the dashboard keeps saying so with the fix attached:

On the machine
sudo loginctl enable-linger $USER

Useful commands afterwards:

On the machine
systemctl --user status termdeck-agent
systemctl --user restart termdeck-agent
journalctl --user -u termdeck-agent -f

macOS

A launch agent is written to ~/Library/LaunchAgents/io.termdeck.agent.plist and loaded. It restarts on a crash but respects a clean exit, and throttles relaunches to once every 10 seconds so a broken build cannot burn a core.

macOS lists it under System Settings, General, Login Items and Extensions as io.termdeck.agent. The installer also unloads and removes any older Termdeck launch agent pointing at the same files, so a reinstall never leaves two agents fighting over one machine.

On the machine
launchctl list | grep termdeck
launchctl unload ~/Library/LaunchAgents/io.termdeck.agent.plist
launchctl load   ~/Library/LaunchAgents/io.termdeck.agent.plist

Windows

A scheduled task named TermdeckAgent is registered with two triggers: at logon, and a repeating check every 2 minutes. If the agent is killed, the 2 minute trigger brings it back. If it is already running, the repeat is a no operation, so there is never a second copy.

The task runs a windowless shim, so nothing appears on your desktop and nothing sits in the taskbar. Registration needs elevation, which is why the installer relaunches itself with a UAC prompt.

If Task Scheduler refuses, the installer still starts the agent for the current session and says clearly that it will not come back after a restart. Rerun the command from an elevated PowerShell to fix that.

PowerShell
Get-ScheduledTask -TaskName TermdeckAgent
Start-ScheduledTask -TaskName TermdeckAgent
Stop-ScheduledTask  -TaskName TermdeckAgent

Machines with no service manager

On a system with neither systemd nor launchd, the installer starts the agent in the background and registers a @reboot cron entry. Recovery is then boot only: if the process is killed it stays down until the machine restarts. If even cron is unavailable, the installer says plainly that the agent will not survive a restart, and the machine card repeats it.

Two badges on a machine card are worth acting on the day you see them. Stops at logout means lingering is off on a systemd user install. Stops at restart means nothing on the machine is registered to start the agent again. Both stay silent on a healthy machine.

Where things live

~/.termdeck/agent/directory

The agent itself and its two dependencies. Safe to delete: the uninstaller does exactly that.

~/.termdeck/agent.envfile, mode 600

The machine token and the master URL. On Windows the equivalent is %USERPROFILE%\.termdeck\agent.env.cmd.

~/.termdeck/logs/agent.logfile

The agent's activity log. Readable from the dashboard through the machine card, so you rarely need to open it by hand.

~/.termdeck/persistence.jsonfile

How the agent was registered on this machine. This is what lets the dashboard tell a durable install apart from one that dies at logout.

~/.termdeck/policies.jsonfile, mode 600

Your auto allow rules and hard deny switches. Written only by Termdeck, enforced by the machine.

Set TERMDECK_HOME before installing to move all of the above somewhere else. Your coding CLIs keep their own directories, which Termdeck reads but never relocates. Those are listed in the settings reference.

Updating

The agent updates itself. When the master ships a new version, connected agents fetch it, restart, and confirm the new build by completing a handshake.

An update is only considered done once that handshake succeeds. Until then a marker on disk says an update is in flight, and two watchdogs undo it: a boot counter catches code that crash loops, and a five minute timer catches code that runs but can never connect. A version that fails either test is rolled back and quarantined, so the same bad build cannot be taken twice.

You can also press Update on a machine card. Being a version behind for a few minutes after a release is normal and the card says so rather than treating it as a fault.

Repair

For the cases the agent cannot fix itself, a wedged supervisor or a half written node_modules, there is a repair script. It uninstalls, reinstalls, and reuses the token already on the machine, so the machine keeps its identity and you do not need the dashboard.

Terminal
curl -fsSL https://termdeck.io/heal.sh | sh

It retries three times. If all three fail it prints the three likely causes in order: Node missing from the path, the machine cannot reach termdeck.io, or npm could not install the two dependencies. The dashboard offers this command on a machine card once a machine has failed to recover on its own.

Uninstall

Terminal
curl -fsSL https://termdeck.io/uninstall.sh | sh

This stops whichever service was registered, removes the unit or task or cron line, kills the process, and deletes the agent directory, the token file, and the persistence marker.

Two things it deliberately does not touch:

  • Your sessions. Transcripts belong to the coding CLIs and stay exactly where they were. Reinstalling later brings the whole history back.
  • The machine entry in the dashboard. Remove it at Settings, Machines as well if you are done with that machine, otherwise it counts against your device limit and shows as permanently offline. It does eventually tidy itself up: a machine we have not heard from in 14 days gets its owner an email naming the date, and one still quiet at 30 days is removed. Its chats are files on that machine and are never touched, but the titles, pins, archive and project list set up for it in Termdeck go with the entry.

Reinstalling and moving machines

Reinstalling on the same machine, for example after replacing the disk, uses the same flow with a fresh token: open the machine card and choose Regenerate token. The master disconnects the old agent the moment the old token dies, so the wizard's live confirmation is accurate for a reinstall too.

Moving a machine name to different hardware is the same operation. Regenerate, run the command on the new box, and every chat that referenced that name keeps working, because routing is by name rather than by address.

Install on every machine you actually work on, including the ones you normally reach over SSH. The point of the fleet view is that you stop caring which box a job is running on.