Getting started

This page takes you from nothing installed to an agent replying on a machine you control. Agents do their work locally through the tama CLI, so getting started is four moves: install it, connect the machine, keep it online, and say hello.

Install the tama CLI

Install the latest tama release on macOS or Linux with one command:

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

On Windows, run the PowerShell installer:

irm https://taskmachine.io/install.ps1 | iex

The installer picks the right binary for your operating system and CPU and verifies the download against the release checksums before installing anything. On macOS and Linux it installs to ~/.local/bin — no sudo, no system-wide files — and prints the exact export PATH=… line to add when that directory is not on your PATH yet. On Windows it installs to %LOCALAPPDATA%\TaskMachine\bin and adds that directory to your user Path for you. Set TAMA_INSTALL_DIR before running the installer to choose a different directory.

If Task Machine support asks you to install a specific version, set TAMA_VERSION:

TAMA_VERSION="0.3.0" sh -c "$(curl -fsSL https://taskmachine.io/install.sh)"

$env:TAMA_VERSION = "0.3.0"; irm https://taskmachine.io/install.ps1 | iex

Connect the machine with tama setup

With the binary installed, connecting the machine is one command:

tama setup

tama setup opens Task Machine in your browser, where you approve this machine and choose which workspaces it may access. Once you approve, the CLI saves the machine's credentials locally and asks one question: whether to start the tama daemon — the background process that keeps this machine connected — automatically when you log in. Accept the default. Setup then leaves the daemon running either way, so the machine reports in and shows up connected with its coding tools already detected. If support gives you a different app URL during private beta, tama setup --api-url <url> uses it.

Running tama setup again later — to add a workspace, or to reconnect after credentials expire — is safe: setup stops the running daemon first, saves the new connection, and starts the daemon again.

Keep the machine online

Agents can only work on this machine while the daemon runs; heartbeats stop within seconds of it exiting and the machine shows offline. If you accepted the start-at-login prompt, you are done — the daemon starts with your session, and on macOS and Linux it also restarts itself after a crash. You can make that choice later or on a machine set up non-interactively with:

tama daemon install-startup

On a Linux server you reach over SSH, install-startup also enables lingering, which keeps the daemon running after you disconnect and starts it at boot; when the system does not allow that automatically, the command prints the loginctl enable-linger line to run.

For a quick session at the terminal, tama daemon runs in the foreground and reports continuously until you interrupt it. tama daemon stop stops a running daemon, wherever it came from. When the daemon runs in the background, its output lands in ~/.taskmachine/daemon.log, which is the first place to look when a machine misbehaves.

Confirm everything is connected

tama status shows the machine's health at a glance: the app URL, CLI version, whether the daemon is running, whether the server is reachable, and — per workspace — the machine's status, last heartbeat, and the coding tools it offers. It stays useful when something is wrong: an unreachable server or expired credentials show up as a labeled line with the command to fix it, alongside the local state.

tama workers lists the coding tools detected on this machine, including missing ones and why. A machine needs at least one supported tool — Claude Code, Codex, Opencode, and the others — before agents can run there; the supported coding tools chapter lists what Task Machine drives. The workspace's Machines settings page shows the same machine from the app side, so you can confirm the connection from either end.

Say hello to your first agent

With a machine online, finish the guided setup in the app: onboarding walks you from workspace to project, goal, playbook, and autonomy level in a few minutes, and it ends in a real conversation — the built-in Strategy agent opens a chat and speaks first. Reply, and the agent picks up the thread on the machine you just connected. That first round trip is the whole product in miniature: you decide in chat, work runs on your machine, and anything needing your judgment comes back to your inbox.

Where the CLI keeps things

The CLI stores its connection in one JSON file, ~/.taskmachine/config.json: the app URL, the connected workspaces, the machine's identity, and the credentials the local process uses. You connect once and the machine stays connected across restarts; when a credential expires the CLI refreshes it on its own, and only asks you to run tama setup again when a refresh is no longer possible. A machine connected by an older release that wrote to the legacy path ~/.config/taskmachine/config.json keeps using that file until it is reconnected.

Agent work itself runs under the execution root — by default ~/.taskmachine/workspaces — with one folder per workspace and task or chat, so each piece of work gets an isolated place to read and write files, and a task against a git repository gets its own clone there. To put agent work somewhere else, set execution_root in the config file to an absolute path:

{
  "execution_root": "/Volumes/work/taskmachine"
}

The machine reports its execution root to the workspace when it checks in, so you can confirm from the app where a given machine runs agent work.

Keep tama updated

Task Machine can require a minimum CLI version before a machine may start new agent work. When a machine reports an outdated version, the Machines page shows an update action and workspace managers get an Inbox nudge; requesting the update lets the machine install the trusted release in the background and restart its daemon on the new binary. You can also update manually:

tama update

tama update --check reports whether a newer release exists without installing it, and tama update --target-version <version> installs a specific release — including an older one, when support asks you to roll back.

Uninstall tama

Removing the startup entry also stops the running daemon, on every platform:

tama daemon uninstall-startup

Then remove the binary from wherever it was installed — command -v tama (or Get-Command tama on Windows) prints the path:

rm "$HOME/.local/bin/tama"

Remove-Item "$env:LOCALAPPDATA\TaskMachine\bin\tama.exe"

That leaves ~/.taskmachine/config.json and the execution root in place, so a later reinstall reconnects with the existing local state. To remove the saved credentials too, delete the config file (and any legacy copy at ~/.config/taskmachine/config.json). The repositories and task folders under the execution root are yours — review them separately before removing anything. You can also delete the machine from the workspace's Machines settings to remove its records from Task Machine.

From here

Onboarding is the guided in-app path this page's machine plugs into, and How Task Machine works gives you the mental model the rest of the docs build on. For day-2 machine operations — freshness, multiple machines, deleting one — see worker machines, and for every tama command and flag, the CLI command reference. If a machine shows offline, troubleshooting starts with the two commands you just learned.