Install Agentrific and run your first task

This guide takes you from a fresh machine to a task running from your phone: install Pi, connect a model account, choose a phone connection, install and start the Agentrific server, prepare pairing, install the phone app, connect it, and choose a project.

Your Mac or Linux server holds your repositories and runs the agents. Your phone sends instructions and shows progress. Run all terminal commands below on the server, under the same OS account. If it is a remote machine, connect over SSH first.

Before you start

Have these ready:

• A Mac or Linux machine with Node.js 22.19 or newer and Git installed.
• Access to a model through a provider supported by Pi: a supported subscription or an API key.
• A Git repository on that machine, with at least one commit, and the tools needed to install and check the project.
• An iPhone or Android phone with access to the Agentrific app. Check the download badges on the Agentrific homepage. A Coming soon badge means that platform’s public download is not available yet; you can prepare the server, but need the app to complete this walkthrough.

Check your terminal tools:

node --version
npm --version
git --version

Keep the server awake and online while tasks run. Agents have the server account’s filesystem and command permissions; their Git worktrees separate changes but are not a sandbox.

1. Install Pi

Pi connects your model accounts and supplies the agent runtime used by Agentrific.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version
pi

You should now see Pi’s terminal interface. See Pi’s installation guide if installation fails.

2. Connect a model account

Type this inside Pi, rather than at your shell prompt:

/login

Choose your provider and complete its login prompts. Then open the model picker:

/model

Select a model available through your account. For provider choices, remote login help and API-key setup, use Pi and model accounts.

Once a model is selectable, exit Pi and return to your shell. Pi does not need to stay open. Agentrific uses the saved credentials under this OS account; later you will choose its own default model in the phone app. Signing into a different coding-agent CLI does not configure Pi.

Checkpoint: Pi lists a selectable model. This confirms configured access; the first task will check that a provider request actually succeeds.

3. Choose a phone connection

Your phone needs an HTTPS address that reaches the server. OpenTunnel is included and is the default; no separate tunnel CLI or account is needed. You can choose another method:

Connection	What to prepare
OpenTunnel	Included with Agentrific. The server saves its tunnel identity and HTTPS address locally.
Tailscale	Install Tailscale on the server and phone, join the same tailnet and enable tailnet HTTPS. See Tailscale setup.
Cloudflared	Install the cloudflared binary on the server. The CLI can create a temporary HTTPS address for your first session. See Cloudflare setup.
Existing HTTPS address	Have your tunnel or reverse proxy forward to http://127.0.0.1:4318.

Tailscale and cloudflared use your installed tools; Agentrific does not install those tools for you.

4. Install the server

In your server shell:

npm install -g @agentrific/server
agentrific --version
agentrific init

Initialization writes configuration to ~/.agentrific/config.json. The installed server stores its state in ~/.agentrific and initially looks for projects in ~/projects. You will choose your repository folder in the app.

5. Start the server and choose a connection

Run in your server shell:

agentrific start

Press Enter to use OpenTunnel, or use the arrow keys to choose another connection method. The CLI reports unavailable tools and why they cannot be used. Local only does not provide an address for a remote phone.

Wait for the terminal to show the running server and its HTTPS address. Leave this terminal open. Tunnels started by this command stop with the server, and a Cloudflared Quick Tunnel gets a new address on the next start.

Checkpoint: in a second terminal on the server, agentrific status returns server status. Keep the backend on its default loopback address; the tunnel handles the phone connection.

6. Prepare pairing on the server

Press p in the running server terminal to display a QR code and a separate six-digit PIN. Alternatively, in your second terminal:

agentrific pair

This creates an invitation for one device. It does not connect the phone yet. The invitation expires after five minutes, so generate a fresh one after installing the app if needed. Each additional device needs its own invitation.

7. Install the phone app

Open the Agentrific homepage on your phone and use the App Store or Google Play badge for your platform. If it says Coming soon, the public listing is not available yet.

Install and open Agentrific. You should see Connect to your server. If you chose Tailscale, make sure it is connected on the phone to the same tailnet as the server.

8. Pair your phone

1. Generate a fresh pairing invitation if the earlier one expired.
2. Scan the terminal QR code with your phone camera and tap its link to open Agentrific. If your camera does not offer to open the app, open Agentrific, tap Scan pairing QR code, allow camera access and scan the same code. For manual entry, press j in the terminal to reveal the JSON, then paste it into Pairing payload. You can also use agentrific pair --show-payload to print the JSON directly. With the standalone pairing command, press Enter or q to finish without revealing it.
3. Enter the separately printed Six-digit PIN.
4. Tap Connect to server.

Use the pairing PIN here, not your model provider’s API key. Keep the QR payload and PIN private: pairing authorizes the device to start agents on your machine.

Checkpoint: the connection form closes and you can access projects and settings. Run agentrific devices on the server to see the paired device.

If pairing fails, generate a new invitation after checking that the server is running and the phone can reach its HTTPS address. 127.0.0.1 on a phone refers to the phone itself. Invitations allow three PIN attempts and one successful redemption; a server restart invalidates unused invitations.

9. Set up projects and the default model

In the app, open Server settings → Projects folder and save the parent folder containing your Git repositories. This is a path on the server, not on the phone.

For example, with this layout, choose ~/projects:

~/projects/
  my-app/       ← Git repository
  my-api/       ← Git repository

The picker discovers direct child Git repositories. If your repository is /home/alex/code/my-app, set the Projects folder to /home/alex/code. Clone any missing repositories on the server first, using your usual Git credentials.

Open your project from the picker. If it is missing, check the parent path, repository layout and the server user’s access to the folder. Install the project’s required language runtimes and package managers on the server before running work.

Next, open Settings → Default model, press Refresh and choose an available model. Agentrific saves this choice for new runs; it does not import Pi’s terminal selection.

Checkpoint: you can open your project’s board and have selected an available default model.

10. Run your first task

On the project board, tap New task. Give it a title such as Explain this project and these instructions:

Read the project documentation and explain how this repository is structured.
List the commands for installing dependencies, running locally and running checks.
Report anything missing from the setup instructions. Do not modify files.

Tap Add task. It should appear in Backlog; creating a card does not start an agent. Tap Start agent, then Open run to follow workspace preparation, agent activity and the response.

Agentrific prepares a separate Git worktree for the run. If preparation or the provider request fails, read the displayed error and fix the reported dependency, Git or model-access problem before retrying.

Checkpoint: the run shows a response about your repository. Send a follow-up asking about one of the commands it found. You have now checked the full path from phone to server to model and back.

You can close the phone app while work runs; the server must remain running. For later tasks that change code, review the task’s Git flow: delivery can merge changes into the project or open a pull request. A task reaches Done when its delivery succeeds or there are no changes to deliver. See tasks and delivery.

Next: advanced configuration

Once your first task works, follow Advanced configuration to choose a stable HTTPS address, run the server as a background service, configure storage and model access, and manage updates and backups.