Install the agent

Requirements

• Node.js 18 or newer, with npm on the path. Check with node --version.
• Outbound HTTPS to termdeck.io and edge.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.
• Room on your plan. Free connects one machine with no card, once your email address is confirmed. For more, start a Starter or Pro trial from Settings, then Billing.

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

edge.termdeck.io is the fallback address. Some internet providers route termdeck.io badly enough to drop the connection every few minutes. When that happens the agent moves to edge.termdeck.io on its own, and moves back once termdeck.io has been healthy for five minutes. The agent log says each time it switches. If your firewall only lets named hosts through, allow both.

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 & accounts, choose Add machine, name it, and copy what the wizard prints. Once the machine connects, the wizard stays open on its last step to get one coding CLI installed and signed in there, then offers Start your first chat.

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.

One token, one machine. Running the same command on a second computer does not connect a second machine: the two agents end up sharing a token, Termdeck keeps whichever connected first, and the machine's row in Settings shows a two agents badge. Every machine gets its own token from its own Add machine.

Running the command again on the same computer is safe. The installer stops the agent that is already running there and starts the new one, so a reinstall never leaves two agents on one machine. If a second agent is started by hand beside a running one, it waits without connecting and takes over only if the first one stops; the agent log says so.

Reading this on a phone? The command has to run on the computer you are connecting, so use Email it to yourself under the command in the wizard and open the message there. The token is single use and expires within the hour, so send it when you are ready to run it; if it lapses, Regenerate token on the machine's page gives you a new one.

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

$env:TERMDECK_AGENT_TOKEN="agt_your_token"; iwr https://termdeck.io/install.ps1 | iex

Or install with npm

If you would rather use npm, the same install is one command on every platform. It runs the same installer as the lines above, so the result is identical.

npx termdeck-agent install --token agt_your_token

Add --yes to skip the read the source prompt. Later, npx termdeck-agent status says whether the agent is installed and running on this machine, and npx termdeck-agent logs prints the end of its log.

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:

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:

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's page in Settings.

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's page in Settings keeps saying so with the fix attached:

sudo loginctl enable-linger $USER

Useful commands afterwards:

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.

If you turned it off there, running the install command again turns it back on. The installer then checks that the agent actually started. If macOS still does not start it, the installer says so in red, starts the agent for the current session, and the machine's row shows a stops at restart badge.

launchctl list | grep termdeck
launchctl kickstart -k gui/$(id -u)/io.termdeck.agent

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.

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's page repeats it.

Where things live

On macOS and Linux, set TERMDECK_HOME before installing to move all of the above somewhere else; the installer records it in agent.env so the agent keeps using it. On Windows the agent always uses %USERPROFILE%\.termdeck. 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.

Every release is signed. An agent installs one only when its signature checks out, every file matches it, and the version is not older than the one already running. Anything else is not installed, and the agent log says why.

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.

An agent waits until nothing is running on its machine before it updates, so a release never cuts a turn off. You can also open the machine's page in Settings, then Machines & accounts and press Update agent under Manage. Being a version behind for a few minutes after a release is normal and the page says so rather than treating it as a fault. An agent too old to run Claude turns says so in the chat instead of starting one.

On a Mac with an agent older than 0.1.956, an update stops the agent and it does not start again until you log in again or restart the Mac. The new version is already installed by then, so this happens once: from 0.1.956 on, a Mac restarts its agent after every update by itself. To bring it back without logging out, run the repair command below.

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.

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

iwr https://termdeck.io/heal.ps1 | iex

With npm, the same repair is npx termdeck-agent repair on any platform.

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 once a machine has failed to recover on its own, and its row in Settings wears a needs repair badge until then.

Uninstall

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

iwr https://termdeck.io/uninstall.ps1 | iex

With npm, run npx termdeck-agent uninstall instead.

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 & accounts 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's page and choose Regenerate token under Manage. 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.