Server setup

Setting up for the first time? Follow Install and run your first task in order. For the transition to a persistent installation, use Advanced configuration. This page is the command and connection reference.

Agentrific runs under your own macOS or Linux account. Agents execute with that account’s filesystem and command permissions. Git worktrees separate changes; they are not a sandbox.

Choose a phone connection

OpenTunnel is included in the server and is the default connection. Alternatively, install Tailscale on the server and phone, or cloudflared on the server. You can also use an existing HTTPS tunnel or reverse proxy. Follow the connection setup instructions for your chosen provider; Agentrific does not install tunnel tools for you.

Install from npm

Install Node.js 22.19 or newer, then install the server CLI:

npm install -g @agentrific/server
agentrific init

Keep the installed Node binary’s path stable if you register a service. Avoid registering a service from an ephemeral npx cache or temporary directory.

Connect your model accounts

Before starting tasks, install Pi and connect your model accounts. Run Pi’s /login on this machine under the same OS account as the server. It supports Claude, Codex, xAI/Grok, OpenRouter and other providers. Check /model in Pi, then choose an available default in Agentrific’s settings. Provider login is separate from device pairing.

Interactive startup

Run agentrific start in your terminal after connecting your model accounts. Startup detects installed tunnel tools and offers connection options. Use ↑/↓ to choose a method and Enter to select it. Unavailable tools show their status above the selector:

• OpenTunnel uses the bundled SDK to create an HTTPS address and saves its tunnel identity under the server data directory. It needs no separate binary or account.
• Tailscale is available when its daemon is connected, HTTPS certificates are enabled, and the CLI can inspect Serve configuration. Agentrific picks an unused HTTPS port and starts a foreground Serve session. Your phone needs Tailscale on the same tailnet. Existing Serve sessions remain in place.
• Cloudflared starts a temporary Quick Tunnel when the binary is available and no default tunnel configuration interferes. The server waits for a registered connection before displaying its address. The URL changes each start. For an existing named tunnel, paste its HTTPS address instead.
• Existing HTTPS address accepts an address from any tunnel provider, or retains the saved address. Manual addresses are remembered.
• Local only starts without a public connection.

Unavailable tools show a short reason. Agentrific does not install tools, log into Tailscale or change tailnet settings. Tunnels it starts are child processes and stop with the foreground server. It leaves separately managed tunnels alone. Temporary URLs are not saved as defaults; the local agentrific pair command reads the active server address. --public-url supplies an existing address directly and skips detection and the menu. Noninteractive starts retain an existing configured public address; otherwise they use OpenTunnel. Choose explicitly with --connection opentunnel, --connection tailscale, --connection cloudflared, --connection existing --public-url https://YOUR-HOST, or --connection local. Save a background-service choice with agentrific init --connection local (or another provider).

Once the server is running, press p to print a fresh pairing QR code and PIN in that terminal, j to reveal its manual JSON payload, or ? to show the shortcuts. The separate agentrific pair command continues to work; press j to reveal the JSON or Enter to finish. Use agentrific pair --show-payload to print the JSON directly. Ctrl+C stops the foreground server. Interactive output shows the local and public addresses, data directory, readable logs and pairing instructions. Colours follow terminal support and NO_COLOR. Services retain structured JSON logs and start without prompts or keyboard shortcuts; --no-interactive also disables them explicitly.

Installed CLI commands store their data in ~/.agentrific. To keep existing sessions, use the same absolute directory with --data-dir or AGENTRIFIC_DATA_DIR; do not copy only the database. Pi conversations and attachments must remain together, and existing worktree paths must remain valid.

Choose an HTTPS connection

The backend binds to 127.0.0.1:4318. Choose one of these options. Device authorization is required for every provider.

OpenTunnel

Run agentrific start --connection opentunnel. Agentrific forwards the HTTPS connection to its loopback server using the bundled OpenTunnel SDK. The relay carries encrypted traffic; TLS terminates locally. Tunnel identity, credentials and certificate material are saved in ~/.agentrific/phone-connection with private file permissions. Keep that directory private and include it in secure backups. Stopping the connection preserves its identity for the next start.

For a local-only server, run agentrific start --connection local.

Desktop app

In Settings, start Run server on this computer, then open Connect your phone. Use OpenTunnel creates the HTTPS address automatically. Once connected, choose Show QR code and PIN and scan it on your phone. The server stays on loopback; no router port forwarding is needed.

Turn Use OpenTunnel off to disconnect it and show Tailscale and cloudflared setup instructions and connection buttons. Tailscale requires both devices on the same tailnet; cloudflared provides a temporary public address. The desktop app manages only the tunnel session it starts. Existing desktop installations retain local-only behavior until OpenTunnel is enabled; fresh desktop profiles enable it when the local server is started.

Tailscale Serve

Install Tailscale on the server and phone, join the same tailnet, and enable HTTPS for the tailnet. Proxy the backend:

tailscale serve --bg http://127.0.0.1:4318

Use the HTTPS URL printed by Tailscale. Access stays within your tailnet. See Tailscale Serve and its CLI reference.

Cloudflare Tunnel

Install the native cloudflared binary. For a temporary development URL:

cloudflared tunnel --url http://127.0.0.1:4318

Use the printed HTTPS URL. Quick Tunnels are temporary and intended for testing. Use a named tunnel with a stable hostname for a persistent installation. Cloudflare terminates client TLS at its edge and proxies to the loopback server. See Quick Tunnels and tunnel setup.

Configure the selected address, then restart the foreground server so its WebSocket Origin allowlist includes that address:

agentrific init --public-url https://YOUR-SERVER-HOSTNAME
agentrific start

If the server is already running, stop it first. Avoid doing this while agents or delivery operations are active. Tunnel hostname changes require updating the configuration and pairing again. Use a trusted HTTPS certificate for remote connections.

Pairing grants and device access

Press p in the running terminal or run agentrific pair in another terminal on the server to generate a QR payload and a separate six-digit PIN. Grants expire after five minutes, allow three PIN attempts and can be redeemed once. Restarting the server invalidates outstanding grants.

agentrific devices
agentrific revoke DEVICE-UUID
agentrific status

Revocation blocks future requests and closes that device’s active connections. It does not stop existing agents or retract bytes already downloaded. Device administration and pairing-grant creation use a local user-owned Unix socket.

User services

After configuring a stable installed CLI and Node path:

agentrific service install
agentrific status
agentrific logs
agentrific service restart
agentrific service uninstall

macOS uses ~/Library/LaunchAgents/com.agentrific.server.plist. Linux uses ~/.config/systemd/user/agentrific.service and systemctl --user; no root daemon or sudo is required. A Linux user service normally follows the user’s login lifetime. Configure lingering separately if you want it to survive logout. Service installation refuses to overwrite an existing definition.

Services capture the current PATH so Git, provider tools, and dependency managers remain available. Other environment variables are not copied. Configure provider access through Pi’s persistent credential storage. Use configuration files for the public URL and projects directory. Logs use launchd’s file output on macOS and the user journal on Linux. Manage log retention using your host’s facilities.

Restart shuts down current agent sessions and marks interrupted runs stopped on recovery. Before a planned restart, pause new work and wait for tracked work to finish:

agentrific maintenance enter
agentrific maintenance drain --timeout-ms 60000

Maintenance blocks new HTTP mutations and automated dispatch while allowing reads, authentication and explicit agent stops. Drain reports pending agent, preparation, delivery, HTTP mutation and update-discovery work. A timeout exits unsuccessfully and leaves maintenance enabled; inspect the blockers and repeat the command. Use agentrific maintenance resume to admit new work without restarting. Maintenance is process-local and resets on restart. This does not provide staged installation or automatic rollback.

Updates

agentrific update --check

This checks @agentrific/server on the official npm registry. The server also checks at startup and every twelve hours. Installation is manual.

Enter maintenance and drain tracked work before a planned update, as described above. Stop a foreground server with Ctrl+C. For a user service, stop it with launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.agentrific.server.plist on macOS or systemctl --user stop agentrific on Linux.

npm install -g @agentrific/server@latest

Restart a foreground server with agentrific start. Restart a stopped Linux user service with agentrific service restart. After macOS bootout, load the service again with launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentrific.server.plist.

Data and backups

Session metadata and ordered events live in ~/.agentrific/sessions.sqlite; conversations and attachments live under the same data directory. Back up the whole directory together with the worktrees and keep recorded paths valid. Use --data-dir or AGENTRIFIC_DATA_DIR to choose another absolute data directory.

Managed worktrees default to ~/.agentrific/workspaces. Set AGENTRIFIC_WORKTREES_DIR to change that location. Existing sessions retain their recorded paths. Run one server per data directory.