Agentrific Server
Run coding agents on your computer or server, and control them from the Agentrific iOS and Android apps. Start work, follow progress, send instructions and review results from your phone while the agents run on your own machine.
This package installs the Agentrific server and the agentrific command-line tool for macOS and Linux. The mobile apps connect to your server; your repositories, model accounts and agent processes stay on that machine. A paired device can disconnect and reconnect without ending a running agent session.
With Agentrific you can:
- Manage tasks and agent sessions across your Git repositories.
- Run coding tasks in separate Git worktrees.
- Follow live progress and send follow-up instructions from your phone.
- Attach images and files to give agents context.
- Pair multiple devices with the same server and revoke access when needed.
Learn more at agentrific.com.
Install and start
You'll need Node.js 22.19 or newer, Git, and Pi on the machine that will run your agents. Install Pi and connect your model accounts using the same OS account that will run the server. See the model setup guide.
OpenTunnel is bundled and is the default HTTPS connection, with no separate tunnel binary or account. Alternatively, install Tailscale on the server and phone, or cloudflared on the server. You can also use an existing HTTPS tunnel or reverse proxy. Agentrific does not install these tools for you. See the connection setup guide.
npm install -g @agentrific/server
agentrific init
agentrific start
The server defaults to port 4318 and stores its configuration and state in ~/.agentrific. Its initial projects folder is ~/projects; you can choose a different folder in the app's server settings.
Claude Code
If Claude Code is installed and logged in under the server's OS account, Agentrific automatically adds a Claude Code model connection. Run claude auth login if login is required, then refresh the model list. The server checks PATH, ~/.local/bin/claude and ~/.claude/local/claude; it also respects CLAUDE_CONFIG_DIR.
Like Pipeline, this connection uses pi-claude-agent-sdk and the official Claude Agent SDK child with your existing CLI login. Pi still owns tools, task history and agent execution. The SDK supplies its compatible Claude executable and handles credential refresh; Agentrific does not copy credentials into Pi or send them to clients. Inherited Claude/Anthropic environment configuration still applies.
When no default has been saved, a ready Claude Code connection becomes the default for new sessions using the first Sonnet model in its catalogue. Saved defaults and existing session selections are preserved. Installed but unauthenticated models appear unavailable with login guidance. Set AGENTRIFIC_CLAUDE_CODE=off before starting the server to disable discovery.
Development runs compile the bridge before starting. Its CLI-login and session-isolation adaptations are compiled into the published package, so npm installations do not depend on a workspace-only Yarn patch.
Connect your phone
Open the Agentrific app on iOS or Android. In the server terminal, accept the default OpenTunnel connection or choose Tailscale Serve, Cloudflare Tunnel, or an existing HTTPS endpoint, then press p to display a pairing QR code. Scan it in the app and enter the separately printed six-digit PIN.
Already paired in the web app? Open Settings → Pair device to generate a QR code and separate PIN for another device. Invitations expire after five minutes and can be used once. The server must have a public HTTPS URL configured (AGENTRIFIC_PUBLIC_URL); restart after changing it. Only share invitations with trusted devices: pairing grants access to run agents as the server’s host user.
Once paired, select a project, create a task and start an agent. The server runs the work and streams progress back to your device. Use HTTPS for remote connections; your phone must be able to reach the configured server address.
See the server setup and pairing guide for connection options and configuration.
Useful commands
agentrific --help # Show commands and options
agentrific start --connection local # Start without a public phone connection
agentrific status # Show server status
agentrific pair # Print a fresh pairing QR code and PIN
agentrific devices # List paired devices
agentrific update --check # Check for a newer server release
Access and permissions
Devices must pair before accessing server commands and events. Coding agents execute with the server user's permissions, so run the server under an account with access only to the repositories and credentials you intend to use.