Skip to main content
The CLI runs the same local runner as Twill Desktop, without a window. Connect a computer you reach over SSH, add its project folders, and keep the runner going. Then start and follow tasks for those projects from Twill on your laptop, the web, or your phone. They run on that computer, with its agent logins and files, like any local project. Requirements: macOS or Linux, Node.js 22 or later, and at least one agent installed on the computer (Claude Code, Codex, or OpenCode).

​
Connect the computer

1

Install the CLI and connect

On the computer:
The command prints a link and a code. Use --name to choose the name Twill shows.
2

Approve it

Open the link on any device where you’re signed in to Twill, check that the code and computer name match, and choose Connect. In the terminal, confirm the account that approved it. The terminal lists the agents it found.
3

Keep it running

Answer yes when connect asks to keep the computer running in the background. The runner then starts right away and again after every restart: a launchd agent on macOS, a systemd user service on Linux.To skip the question, pass --service (install) or --no-service. Later, use twill computer service install or uninstall. To run it in the terminal instead, use twill computer start and press Ctrl+C to stop.
4

Sign in the agents

Agents use this computer’s own logins. Sign in once in its terminal: claude auth login, codex login --device-auth, or opencode auth login.
5

Add projects

Several folders make one project. Projects appear in the project picker on all your devices, without restarting the runner.
twill computer status shows whether the computer is online, its projects, and which agents are signed in. twill computer logs -f follows the runner’s log.

​
Keep it reachable

  • macOS: while the runner runs, the computer doesn’t idle-sleep (--allow-sleep turns this off); the display can still sleep. The service starts when you log in, so turn on automatic login for a Mac that should come back on its own after a power cut.
  • Linux: run sudo loginctl enable-linger $USER so the service keeps running while you’re logged out.

​
How it relates to Twill Desktop

A computer is the same whether Desktop or the CLI runs it: they share one connection on that computer, so installing Desktop later doesn’t add a second one. Only one of them runs the runner at a time. Adding folders works from either, while reviewing local files (Changes) needs Desktop on that computer.

​
Disconnect

This stops running tasks, removes the background service, and disconnects the computer from Twill. Project folders and agent logins stay on the computer. Run twill computer connect to connect it again with the same projects.
Anyone who can use this computer’s account can run its agents and read the projects you add. Connect only a computer you control, and approve only a connection you started yourself.