> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run agents on a headless computer

> Connect a computer without a screen, such as a Mac mini or a Linux box, from its terminal and send it tasks from your other devices.

The [CLI](/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](/local-execution).

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

<Steps>
  <Step title="Install the CLI and connect">
    On the computer:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g @twillai/cli
    twill computer connect
    ```

    The command prints a link and a code. Use `--name` to choose the name Twill shows.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Add projects">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    twill computer add ~/code/my-app
    twill computer add ~/code/api ~/code/web --name "Shop"
    ```

    Several folders make one project. Projects appear in the project picker
    on all your devices, without restarting the runner.
  </Step>
</Steps>

`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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
twill 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.

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.