Troubleshooting

Most problems in Task Machine come down to one of a few places: a machine that stopped reporting, a worker that is detected but not turned on for agents, credentials that have gone stale, or a sign-in that did not complete. This page walks through each one — what you are seeing, why it happens, and how to fix it — grounded in how the system actually behaves. For the commands referenced here, see the CLI command reference. For how machines connect, see worker machines.

A machine shows as offline

A machine appears offline when Task Machine on that computer has stopped sending fresh heartbeats. The machine reports on a fixed interval, and its last report is considered stale after thirty seconds, so a machine whose local process has quit, lost its network, or been put to sleep will drop to offline shortly after. A persisted offline status also reads as offline regardless of timing.

To bring it back, run tama status on the machine first: it shows whether Task Machine on your computer is running, whether the server is reachable, and each workspace's machine status and last heartbeat — and when credentials have expired it prints the exact tama setup command to reconnect. If Task Machine is stopped, start it with tama daemon; when it runs in the background instead, its output in ~/.taskmachine/daemon.log explains what went wrong. Once the machine is reporting again, its last-seen timestamp in the workspace's worker settings updates and the status returns to online. If you want it to come back on its own after a reboot, install it as a startup service with tama daemon install-startup.

A worker is detected but agents cannot use it

A coding tool can be present on a machine and still be unavailable to agents, because detection and agent-availability are two separate things. The machine detects whether a tool is installed and reports it. Whether agents may route work to that worker is a workspace setting you control. A newly detected worker is not automatically open to agents until someone enables it.

Confirm the tool is detected first — tama workers lists every supported tool on the machine, marking each available or missing with the reason. If the tool shows as available but agents still are not using it, open the workspace's worker settings and enable that worker for agents. A worker is usable by agents only when its machine is reporting fresh heartbeats and the worker is enabled for agent use.

The CLI says credentials are invalid

Task Machine renews a machine's saved connection automatically, so routine expiry is invisible. When that connection can no longer be restored, the CLI tells you to run tama setup again. The configuration lives at ~/.taskmachine/config.json, or the legacy ~/.config/taskmachine/config.json for a machine connected by an older release. Running setup creates a fresh connection.

If Task Machine support gave you a custom app URL during setup, reconnect with the same --api-url value so the CLI returns to the right workspace connection.

The CLI must be updated

Task Machine can require a minimum tama version before a machine may start new work. An outdated machine can still check in, but new agent work waits until the binary is current. Open the workspace's Machines page and use the update action when it is offered. If the page marks the update as manual, update directly on the machine and then start Task Machine again:

tama update

If the binary is too old to support self-update, reinstall from the Task Machine installer and then restart Task Machine on that computer:

curl -fsSL https://taskmachine.io/install.sh | sh
tama daemon install-startup

irm https://taskmachine.io/install.ps1 | iex
tama daemon install-startup

Connecting a machine does not finish

tama setup opens a browser and waits for you to approve the machine and choose its workspaces. It keeps polling until you approve, deny, or the approval window expires. If the browser does not open automatically, the command prints the URL to open by hand — finish the approval there and the CLI continues. An approval that times out reports that it expired and asks you to run tama setup again. A denied approval stops with that result. Setup needs at least one workspace selected, so approve the machine into a workspace rather than approving with none chosen.

A magic-link sign-in does not arrive

Signing in as a person uses a magic link sent to your email. If the link never arrives, first check that the address you entered is correct, look in spam or quarantine, and request a new link. If several attempts still do not arrive, contact Task Machine support or ask your workspace owner to confirm you were invited with the right address.

An action you expect is missing

When a button or page you expect is not there, the usual cause is that your role does not carry the permission for it. Task Machine hides actions a role cannot perform instead of showing disabled controls, and a reachable page you lack permission for shows an empty state rather than the controls. This applies to agents too: an agent's role is the floor on what it may do. Ask a workspace owner or admin to adjust your role, and see the permissions reference for which key gates the action.

From here

If a problem traces back to how a machine connects and reports, worker machines covers that path end to end. For a problem that is really a permission boundary, the permissions reference maps every action to its key.