Troubleshooting

Most problems in Task Machine come down to one of a few places: a machine that stopped reporting, a runtime 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 and the daemon connect, see runtime, machines, and the daemon.

A machine shows as offline

A machine appears offline when its daemon has stopped sending fresh heartbeats. The daemon reports on a fixed interval, and a machine's last report is considered stale after thirty seconds, so a machine whose daemon 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, confirm the daemon is running on the machine with tama daemon, and check that it can connect to Task Machine with tama status — a healthy connection prints ok. Once the daemon is reporting again, the machine's last-seen timestamp in the workspace's runtime settings updates and the status returns to online. If you want the daemon to come back on its own after a reboot, install it as a startup service with tama daemon install-startup.

A runtime 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 daemon detects whether a tool is installed and reports it; whether agents may route work to that runtime is a workspace setting you control. A newly detected runtime is not automatically open to agents until someone enables it.

Confirm the tool is detected first — tama runtimes 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 runtime settings and enable that runtime for agents. A runtime is usable by agents only when its machine is reporting fresh heartbeats and the runtime is enabled for agent use.

The CLI says credentials are invalid

When a machine's stored access token has expired, the CLI refreshes it automatically against the saved refresh token, so routine expiry is invisible. If the refresh token itself is no longer valid — revoked, expired, or from a workspace the machine was removed from — the CLI cannot recover on its own and tells you to reconnect the machine by running 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 rewrites it with fresh tokens.

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 daemon says the CLI must be updated

Task Machine can require a minimum tama version before a daemon may start new work. An outdated daemon can still check in and receive update requests, but new agent work waits until the binary is current. Open the workspace's Machines page and use the update action for the affected machine, or update manually on the machine:

tama update

If the binary is too old to support self-update, or if the machine is running Windows where self-update is not yet supported, reinstall from the Task Machine installer and then restart the daemon:

curl -fsSL https://taskmachine.io/install.sh | sh
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, runtime, machines, and the daemon covers that path end to end. For a problem that is really a permission boundary, the permissions reference maps every action to its key.