# Intent on remote machines

You can run the Intent background service (`intentd`) on a separate computer, such as a Linux server, a spare Mac, or a Windows PC, and control it from the desktop or iOS app. Your workspaces and agents are stored on that computer.

Once connected, see [Multi-device support](https://intentapp.dev/docs#multi-device-support) to move workspaces between computers, or [Intent mobile](https://intentapp.dev/mobile) to use the iOS app.

You can also run the Intent web app on a server and use Intent from a browser, with no desktop app installed. See [Use Intent in a browser](https://intentapp.dev/docs/remote#web).

## Check requirements

On the remote computer, install:

- **git** (required)
- **Node.js** with npm (required, used to run coding agents)
- **GitHub CLI** (`gh`) (optional, connects Intent to GitHub without a manual token)

## Install intentd

Use the option for your system.

### macOS or Linux

```bash
curl -fsSL https://github.com/intent-hq/intentd-releases/releases/download/sitter-latest/install.sh | sh
```

### Windows (PowerShell)

```powershell
powershell -c "irm https://github.com/intent-hq/intentd-releases/releases/download/sitter-latest/install.ps1 | iex"
```

### Homebrew

```bash
brew install intent-hq/tap/intentd
brew services start intentd
```

### Debian or Ubuntu

```bash
sudo apt install ./intentd_amd64.deb
systemctl --user enable --now intentd
```

The install script asks whether intentd should start automatically when you log in. To answer yes without the prompt, set `INTENTD_INSTALL_SERVICE=1`. If you decline, start it manually with `intentd start`.

On a Linux server with no display, run this so intentd starts when the machine boots:

```bash
sudo loginctl enable-linger $USER
```

## Allow other devices to connect

Apps connect on port **5181**. At first, intentd only accepts connections from the same computer. Choose one way to open access:

- **Local or Tailscale network:** set `server.bindAddress` to the computer’s network IP address, a list of addresses, or `0.0.0.0` for all addresses. Use this when your devices share a home or office network, or are all on the same Tailscale network. Apps connect directly to the computer, but only from devices that can reach it on that network.
- **Tunnel:** set `server.tunnel.enabled` to `true`. The computer gets a permanent address starting with `tc`. Use this to reach the computer from anywhere, such as a phone on mobile data or a cloud server behind a firewall, without opening ports or setting up a VPN. To also block direct local network connections, set `server.tunnel.only` to `true`.

Change any setting with:

```bash
intentd settings <name> <value>
```

For example: `intentd settings server.tunnel.enabled true`

## Get pairing details

On the remote computer, run:

```bash
intentd pair
```

You’ll see a QR code, a URL, a **bearer token** (a password-like key), and a **TLS fingerprint** (a code that identifies the computer’s security certificate).

Useful options:

- `intentd pair --png pair.png` saves the QR code as an image.
- `intentd pair --rotate` creates a new token and disables the old one.
- `intentd pair --host <address>` uses a specific host name or IP address in the pairing details. Use it when the app should connect through a different address than the one intentd detects.

If the connection listener is off, `intentd pair` offers to turn it on with no restart. Add `--yes` to accept automatically in scripts.

If the computer still accepts only local connections and no tunnel is running, pairing stops and tells you which setting to change.

### intentd in WSL

If intentd runs inside WSL on a Windows PC, run this inside WSL:

```bash
intentd pair --host localhost
```

Then add the machine in the Windows desktop app with **Host** set to `localhost`.

## Connect from an app

### Desktop app

The quickest way is to open the `intent://` link that `intentd pair`prints. The desktop app opens and fills in the connection details for you.

To add the computer by hand:

1. Go to **Settings → Machines → Add machine**.
2. In **Connect to another intentd**, enter the **Host**, **Port**, and **Access token** from `intentd pair`. Give the machine a **Device name** you’ll recognize.
3. Click **Continue**. The app shows the computer’s certificate fingerprint. Check that it matches the TLS fingerprint printed by `intentd pair`, then select **Confirm & connect**.

The form also includes:

- **Detect all backend IPs**, which finds the other IP addresses the computer can be reached on.
- **Save to iCloud** (Mac only), which saves the machine so your other Apple devices can connect to it.

To check a machine you’ve already added, open its **Edit** panel and select **Test connection**.

### iOS app

Scan the QR code from `intentd pair` with the app’s pairing scanner. The desktop app can also display a QR code for its current connection under **Settings → Mobile → Intent Mobile → Show QR Code**.

On the first connection, the app saves the computer’s fingerprint and checks it every time you reconnect.

## Use Intent in a browser

The Intent web app (`@intent-hq/web`) runs Intent on a server with no desktop app, such as a VPS or a dev box. You then use it from a browser on your other devices.

### Start the web app

On the server, run:

```bash
npx @intent-hq/web
```

This needs Node.js 22.22.2 or later, 24.15.0 or later, or 26 or later. The web app listens only on `127.0.0.1:47120`, so at first it can only be reached from the server itself. The first time it runs, it prints an access key. Use this key to sign in.

### Manage sign-in

- `npx @intent-hq/web key` shows the access key again.
- `npx @intent-hq/web key --reset` creates a new key and signs out every browser.
- `npx @intent-hq/web link` creates a single-use sign-in code that expires after 10 minutes. Add `--url https://…` to create a sign-in link for the address you use to reach the web app.

A browser stays signed in for 400 days after its last visit.

### Reach it from other devices

Put the web app behind a private HTTPS front end that only your own devices can reach. For example, with Tailscale:

```bash
tailscale serve --bg 47120
```

Then open the HTTPS address that Tailscale shows from any device on your Tailscale network.

**Do not use Tailscale Funnel or any other public tunnel.** These make the web app reachable from the public internet.

### Add machines

If intentd is already running on the same server, it appears in the list as **This machine (local)**. To add another computer, run `intentd pair` on it and enter its host, port, and token in the web app.

### Security and limits

- The web app’s data directory, `~/.local/state/intent-web`, stores machine tokens in plain text. Protect it the same way you would protect an SSH key.
- The web app doesn’t include the **Mobile** tab, iCloud sync, or native file dialogs.

## Tips

- Each workspace and agent belongs to one computer. If something seems missing, check which machine is active in **Settings → Machines**. The list labels this computer **(local)** and the computer the app is currently using **(connected backend)**. Icons show each machine’s operating system and AI providers.
- To view a dev server running on the remote computer, open `http://daemon.localhost:<port>` in the app’s built-in browser. The desktop app forwards the port for you.
- Treat pairing links, QR codes, and tokens like passwords. If one leaks, run `intentd pair --rotate`.
- Scanning a QR code shares connection details only. Confirm separately that your device can reach the remote computer over the network.
