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 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 a second route to the same service. Some internet providers route termdeck.io slowly, or badly enough to drop the connection every few minutes. The agent times both addresses when it starts and connects through the faster one. While it runs it checks again every 15 minutes and moves only when the other address is clearly faster twice in a row. If the connection it is using fails, it moves to the other address at once. The agent log says which address it picked and each time it moves. 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.

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

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.

Terminal or PowerShell
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.

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

Linux with systemd

A user unit is written to ~/.config/systemd/user/termdeck-agent.service and enabled. Restart policy is