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 to move workspaces between computers, or Intent 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.

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

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

Windows (PowerShell)

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

Homebrew

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

Debian or Ubuntu

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:

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:

intentd settings <name> <value>

For example: intentd settings server.tunnel.enabled true

Get pairing details

On the remote computer, run:

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:

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 pairprints. 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:

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:

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.