Standalone CLI

The CLI runs AgentGrid's daemon on a Mac or Linux host. Connect from the AgentGrid desktop app to work on projects stored there. Your phone currently connects through the desktop app; an independent daemon does not provide phone connectivity or appear in Your computers by itself.

Requirements and availability

Choose macOS Apple Silicon (arm64), macOS Intel (x64), Linux x64, or Linux arm64 on the download page. Downloads appear only after all four versioned tarballs are published; Coming soon means there is no CLI download yet.

The archive bundles Electron and matching native modules, so you do not install Node.js or rebuild addons. Linux still needs Electron's system libraries, including GTK, NSS, X11/AT-SPI and libsecret dependencies, even with no window. Minimal Linux hosts may need their distribution's packages; these Linux builds target glibc, not Alpine/musl.

Install and sign in to the coding harnesses you need on the host, as the same OS user running the daemon. Signing in on your laptop does not sign in the remote host. See Coding harness setup.

Install and run

Download one matching tarball into a new, empty directory. From that directory:

tar -xzf ./AgentGrid-CLI-*.tar.gz
./agentgrid-cli/bin/agent-grid-daemon --help
./agentgrid-cli/bin/agent-grid-daemon run --idle-shutdown-ms 0

Keep the running terminal open. 0 disables the default five-minute idle exit. The stable daemon uses port 8765; if another daemon owns it, use that host's existing service or stop it before starting this one.

In a second terminal on the same host, from the same installation directory:

./agentgrid-cli/bin/agent-grid-daemon pair --label laptop

This prints a short-lived pairing code. Run it only after your daemon has started; it contacts the local daemon on port 8765.

Connect from desktop

In the desktop app's advanced settings, enable Keep workers and terminals running in the background and restart if needed. In Settings → Devices, under Computers you can access, choose Connect, then Use a code instead. Fill Pairing code with the host's code and Computer address with its Tailscale address and port 8765. Both computers need to be reachable over your tailnet.

For an SSH tunnel instead, restart the host daemon with the explicit loopback-forward opt-in:

./agentgrid-cli/bin/agent-grid-daemon run --allow-local-forward --idle-shutdown-ms 0

On your laptop, keep this tunnel open, replacing user@host with your SSH destination:

ssh -N -L 18765:127.0.0.1:8765 user@host

Pair in desktop using 127.0.0.1:18765 and a code minted on the host. Do not expose the daemon's plain WebSocket port publicly. Once paired, open a remote project from the desktop's remote connection panel.

Share a project on a fresh headless host

Remote projects must be explicitly shared. Before running the daemon on a fresh host, create ~/.agent-grid-daemon/shared-projects.json with this format, replacing the path and name:

[
  { "path": "/absolute/path/to/project", "name": "My project", "addedAt": "2026-10-27T00:00:00.000Z" }
]

addedAt is required. Use an existing absolute project path. Preserve any entries already in this file; do not replace an existing shared-project list with this example. If you changed the data directory, put the file there instead.

Data, logs and upgrades

Data defaults to ~/.agent-grid-daemon; logs are in ~/.agent-grid-daemon/logs/daemon.log. AGENT_GRID_DAEMON_DATA_DIR selects another directory; use the same value for every run and after upgrades. Keep that directory to retain pairings and host state.

To upgrade, finish active work, stop the foreground daemon with Ctrl+C (or stop your own service), and extract the new download into a new, empty directory. Start its launcher with the same data directory. Extracting over an old runtime leaves obsolete files behind. There is no built-in CLI updater.

Troubleshooting

• Missing shared library: install the Linux library named by the loader error using your distribution's package manager.
• Wrong architecture or addon ABI: download the matching complete tarball again; keep its Electron runtime and native modules together.
• Pairing fails: confirm the daemon is running, mint a fresh code on that host, and check Tailscale or the SSH tunnel and opt-in flag.
• No remote projects: check the shared-project file's absolute paths and required fields, and the host user's directory permissions.
• Harness unavailable: check installation and sign-in as the daemon's OS user on that host, then inspect the daemon log.