Troubleshooting

Check your spam or promotions folder first. Then open Settings, then Account and choose Resend email; the window names the address the link went to. If that address is wrong, choose Change address there and the link goes to the new one. With a card on your plan you can connect a machine while you wait, so the email does not hold up setup.

A link works for 7 days. If it is older than that, opening it sends a new one to the same inbox and the login page says so; open the newest email. If the login page instead asks you to send one yourself, log in and use Resend email in Settings, then Account. Work mail scanners often open links before you do: if your address is already confirmed, the link says Your email is confirmed rather than calling it expired.

The login page says which of three things happened. Cancelled means Cancel was pressed on GitHub's screen; choose Continue with GitHub again. Took too long or lost its cookie usually means the sign-in started in an app's built-in browser or sat open for more than 10 minutes; open termdeck.io in your regular browser and try again. Did not finish is on GitHub's side or ours; wait a moment and retry, or sign up with an email and a password instead.

An account made with GitHub has no password until you add one. Choose Continue with GitHub, or choose Forgot? and follow the emailed link to set a password for email log in.

A network can create a handful of accounts an hour, and a shared office or mobile connection shares that allowance. Typos and too-short passwords do not count against it. Wait for the countdown on the button, or choose Continue with GitHub, which is not limited this way.

Checkout is run by Airwallex, our payment provider, and its page is headed by the legal merchant, Vortiq LLC, the company behind Termdeck. It is the right page. The payment page can take a few seconds to load after you press a plan's button; the trial screen says Opening secure checkout… until it does.

Connecting a machine needs a plan, and a new account has none until it starts its trial. Choose a plan on the Start your 14-day free trial screen, or from Settings, then Account, and enter a card at checkout. The card is not charged until day 15, and cancelling before then costs nothing. If you already had a plan and it lapsed, subscribing again from the same page brings everything back.

Sometimes the human check needs a click. A Verify you are human box appears above the button, and the button reads Tick the box above to continue until you tick it. Once you do, the form carries on by itself; there is no need to press the button again. If the box never appears, a blocker or a strict network may be stopping challenges.cloudflare.com.

Sign up refuses throwaway inboxes from temporary mail services, and addresses at a domain that cannot receive mail. Use an address you keep, such as your work or personal mailbox, or sign up with GitHub instead. Private relay addresses from services like Proton, iCloud or Firefox Relay are fine. If an address you use every day is refused, email [email protected] from it.

Several tries in a short time from one network or for one address pause the form for a while. The button counts down and comes back on its own when the wait is over, so there is nothing to reload. If you have forgotten the password, Forgot? on the log in page emails a reset link, and Continue with GitHub works throughout if your account uses it.

Without a card on your plan (for example, a plan from a redeemed code), connecting a machine needs a confirmed address, so the wizard stops until the link we emailed you has been opened. The window that stops you names the address the link went to and has Resend email on it. Nothing in the inbox after a minute or two, spam folder included, usually means the address is not the one you think it is.

Choose Change address in that same window, type the right one, and we send a new link there. Settings, then Account has the same button under Wrong address? if you closed the window. Any link already sent to the old address stops working the moment you change it.

An address that is already confirmed cannot be changed this way, because a confirmed address is what password resets go to. Email us to move one.

Node 18 or newer is not on the path for the shell you ran the command in. Install it from nodejs.org and check with node --version.

If Node is installed through a version manager such as nvm, it may exist in your interactive shell and not in a background service. Install a system wide Node as well, or point the agent at the right one.

The command was run without its token, usually because it was retyped rather than copied. Go back to the connect wizard and copy the whole line. If the wizard is gone, open the machine card and choose Regenerate token.

Usually a network or proxy problem between the machine and Termdeck. Check the machine can reach it at all:

curl -fsSL https://termdeck.io/VERSION

If that fails, the machine cannot reach termdeck.io and nothing else will work until it can. On a corporate network, allow outbound HTTPS to that host.

Scroll up in the output for npm's own error, which is the real one. Common causes are a proxy that npm is not configured for, a registry that is unreachable, and a permissions problem in the npm cache.

After fixing it, run the repair command rather than the installer, so a half written install is cleared first:

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

Task Scheduler denied access, so the agent is running for this session only and will not come back after a restart. Open PowerShell as administrator and run the install command again.

The machine card will keep showing a stops at restart badge until this is fixed.

Look for a two agents badge on the machine card. Two agent processes connected with one token knock each other off the connection, so the machine reports online while every request to it times out.

The usual cause is the install command pasted on a second computer. A token belongs to one machine; the second one needs its own from Add machine. Stop the agent you did not mean to run and the machine settles within a minute.

Without that badge, a timeout usually means the agent is busy with a long turn, or is restarting to apply an update. Both clear on their own. If neither is true, the machine card has Run checks.

One thing that looks like a timeout is not one. If a single feature answers straight away with agent is out of date, the rest of the machine is fine: that machine is running an older agent than the feature needs. It updates itself, usually well within the hour. Updating covers doing it now.

The machine is connected and still reading its chat history, which happens right after it connects and again after a Termdeck update. Its chats fill in on their own, usually within seconds, and the chats on your other machines are already listed. If it stays on catching up for minutes, the machine is up but slow to answer, and a laptop on a weak connection is the usual reason: give it a moment, or check that machine's connection. See Machines and fleet.

Work through these in order.

1. Is the machine awake? Sleep is by far the most common answer. A closed laptop is an offline machine.
2. Does the card carry a warning badge? Then it died at a logout or a restart and the badge names the fix.
3. Is the service running?

# Linux
systemctl --user status termdeck-agent

# macOS
launchctl list | grep termdeck

Get-ScheduledTask -TaskName TermdeckAgent

4. Can it reach Termdeck? curl -fsSL https://termdeck.io/VERSION
5. Still nothing? Run the repair command. It reuses the token already on the machine.

A systemd user service without lingering. Systemd shuts your user services down at logout unless lingering is enabled. Run this once on the machine:

sudo loginctl enable-linger $USER

The installer attempts this and can only fail when sudo needs a password it cannot prompt for, which is normal for curl | sh.

Nothing is registered to start it. Rerun the installer, on Windows from an elevated PowerShell. The machine card's stops at restart badge disappears once a proper service exists.

Termdeck checks each added folder once per page load and marks the folder name on that project's rows when the machine says it is not there. The chats stay listed, because their transcripts are still on disk and still readable. What will not work is starting a new chat in that folder.

Either put the folder back where it was, or remove the project in Settings, then Projects and add it at its new path.

Online means the agent is connected, not that the machine can run a turn. The agent brings no coding agent with it. Check the engine rows on the machine card: a machine with no CLI installed, with one installed but signed out, or with a saved login the provider has since refused, is connected and useless. The dashboard says which of the three it is, above the chat list, and the New chat page repeats it before it lets you type.

Re-run the install command on that machine. It stops the agent that is already running, retires any old launch agent left over from an earlier install on macOS, and starts one fresh agent. A second agent started on the same machine does not connect: the agent log shows a line saying it is standing by for the running one, and it takes over only if that one stops. If the two agents are on different computers sharing one token, see the two agents badge on the machines page.

This is the most reported symptom and it nearly always has one cause: the CLI is not signed in, so it cannot list models. The menu itself names the machine and prints its reason, and the Fix this in Machines & accounts button under it opens that machine's card with the sign ins for that engine already expanded. Run checks names the same thing, with the CLI's own reason attached.

claude          # starts the Claude Code login
codex login
grok login

If the login is fine and the catalog still fails, the reason string on the check row is the CLI's own and is the thing to act on.

The model never answered: Claude Code got an error back instead and wrote it into the chat. Termdeck shows it as a notice rather than a reply, with Claude Code's own sentence and the next step. Signed out means the login on that machine expired: run claude there and sign in with /login, or switch to another saved account in Settings, then Machines and accounts. A usage limit says when it resets; send again after that, or switch account. For a model that is not available, pick another one. Anything else is a failed request, and sending the message again retries it.

Termdeck looks the binary up the way your shell does. A background service does not inherit your login shell's environment, so a CLI that only works after your shell profile has run will not be found.

Name it explicitly in ~/.termdeck/agent.env and restart the agent:

TERMDECK_CLAUDE_EXE=/full/path/to/claude
TERMDECK_CODEX_EXE=/full/path/to/codex
TERMDECK_GROK_EXE=/full/path/to/grok

Check whether the machine has two copies of that CLI on the path, for example an npm global and a package manager install. When it does, the lookup that runs turns and the lookup that drives the sign in can land on different binaries, and the sign in never completes.

Remove the copy you do not want, or pin the right one with the executable variables above.

The machine did not answer the status question. This is not the same as signed out and Termdeck will not treat it as such. It usually clears on its own. If it persists, look at the agent log from the machine card.

Another process is attached to that session, typically a terminal running the CLI on the same chat. Two writers on one transcript would fork it, so Termdeck goes read only instead.

Exit the CLI in that terminal, or start a new chat in the same folder. The composer unlocks by itself once the other process lets go.

In order of likelihood:

• The machine is offline. The sidebar and the machine card both say so.
• The chat says the machine's agent is out of date. Claude turns need an agent from a recent release. It updates itself as soon as nothing is running on the machine, usually within a minute; press Update on the machine card to do it now, then send again.
• The engine is not signed in on that machine.
• The engine has a saved login the provider refused. The card reads Sign in expired. Run the engine once on the machine to refresh it.
• The session is attached to another process, so the composer is locked.
• A run is already in progress. On a paid plan the message is queued instead of refused.
• The account has no plan, or its plan has lapsed. Start the 14-day free trial, or subscribe again, from Settings, then Account.

Check for a waiting approval first, in the transcript or on the Approvals page. A blocked run looks exactly like a slow one until you find the card.

If the engine is retrying a failed provider call, the transcript says so with an attempt count rather than sitting silent. If neither applies and it has genuinely stopped moving, press Stop and send the prompt again.

Three candidates:

• A hard deny refused it. The transcript says which guard and why.
• A PreToolUse hook in your CLI settings blocked it before Termdeck saw it. Run checks lists armed hooks.
• A settings file does not parse, so the engine is ignoring it entirely along with everything configured in it. Run checks flags this as a failure, and it is the highest value row on the page.

The server asked for input mid call, a form or a sign in link, and Termdeck cannot show that prompt yet, so it answered cancelled rather than leave the turn waiting. For a sign in, authenticate the server once from /mcp in a terminal on that machine. See When a server asks you something.

You did not. Closing a tab, losing a connection, sleeping a laptop, and a Termdeck release all leave the process running on your machine. The agent keeps the run going and catches you up on what you missed when you come back.

A run with nobody attached is kept for a few minutes. Past that it is stopped, and everything it wrote is still on disk in the transcript.

Press Compact, or send /compact. The engine summarises the conversation so far and continues with the shorter version.

Compacting loses detail. If the chat has drifted a long way from what you want, a fresh chat in the same folder is usually better than compacting a long one.

That machine has TERMDECK_FULL_ACCESS=off in its agent settings, so it refuses Full access on every engine. Pick another mode from the composer and send again. To allow Full access there, remove the line from ~/.termdeck/agent.env and restart the agent. See Turning Full access off.

Turn it into a rule. Settings, then Approvals, add a rule for the tool with a glob that matches the command, and a maximum risk cap. It stops asking from the next turn.

Keep the glob tight. npm test is a rule; * is a permission mode with extra steps.

Three things to check, in order:

• The risk cap. A rule only fires when the computed risk is at or below its cap. A command that scores high under a low capped rule will still ask.
• The tool name. The rule must name the tool the engine actually used.
• The glob. It matches the command for shell tools and the path for file tools.

The rules list shows a match count per rule, so a rule that has never fired is easy to spot.

A hard deny guard tripped. The message names which one. If your work genuinely needs it, for example a chat whose job is provisioning a machine, switch that guard off in Settings, then Approvals and switch it back on afterwards.

Guards cannot be switched off from anywhere else, and no auto allow rule can override one.

Auto approve needs a paid plan. When a trial ends, saved rules are paused rather than deleted, and the settings page says paused instead of pretending they are still in force. They resume the moment you subscribe.

Safari only allows web push for a site added to the home screen. Add Termdeck from the share menu, open it from that icon, and enable push there. A subscription made in a Safari tab does not carry over.

A Termdeck window you are using keeps push off on every device. Leaving it, or three minutes with no typing, clicking, or mouse movement in it, hands alerts back to your phone. See while you are using Termdeck.

Browsers expire push subscriptions, especially after a long idle period or a data clear. Toggle push off and on in Settings, then Notifications to register a fresh one for that device.

The count, the bell, and the Approvals page are all computed from one list, so they cannot disagree. What counts is a waiting permission, a waiting question or plan, and a turn that failed. Open the bell to see the entries.

Chats appear only for folders you have added. Add them in Settings, then Projects. If chats you started in a terminal are missing specifically, check the visibility switches in Settings, then Chats.

A chat running in a git worktree is folded into its base repository rather than appearing as a separate project.

On Starter you can add 2 projects. A chat started in a third folder runs, but stays out of the sidebar until you remove a project or move to Pro. Plans and limits has the limits.

If a folder you added is in Your projects but its chats are not in the sidebar, the row says why: the machine is offline, the machine is no longer on your account, the entry is a worktree whose chats are listed under its repository, or that machine has no chats in the folder any more. Remove the row, or fix the machine, whichever the line asks for.

Starter has limits Pro does not: 1 machine, 2 projects, 2 saved logins per engine, the last 7 days of usage, and 4 terminals in a window. Adding past one of them opens the prompt instead. Nothing you already have is removed. Remove something to make room, or move to Pro from Settings, then Account.

Check the Archive page. Auto archive moves anything untouched for the period you set, and nothing is ever deleted. Termdeck does not delete transcripts under any circumstances: they belong to the CLI and live on your disk.

The Explorer section is closed. Its close button sits beside its maximise button in the Explorer's own title bar, and closing it leaves the file reader on its own, saying "Select a file to view it" over an empty panel. The choice is remembered per browser, so reopening the dock, switching chat or reloading the page will not undo it.

Bring the tree back with the folder button at the left of the reader's title bar, or by pressing the Files tab.

A stale cached asset. Do a hard reload. If that does not settle it, Settings, then Data and reset clears this browser's local Termdeck data. Nothing on your machines is affected: layout and preferences are per browser, and everything that matters is on disk.

If it says connecting a machine needs a plan, your account has no plan yet. Press Choose a plan and pick one; every plan starts with a free trial, and you can add the machine as soon as it is active.

Otherwise you are at your plan's device limit. Remove a machine you no longer use, or move to a plan with more room. The dashboard also lists machines currently being refused for being over the cap, since that refusal otherwise happens in a terminal nobody is watching.