Connect your coding models with Pi

For the complete installation sequence, start with Install and run your first task. Use this page for provider choices, credential configuration and model troubleshooting.

Agentrific uses Pi to run coding tasks on your server. Install Pi’s terminal CLI to connect your model accounts, then choose a default model in Agentrific. Complete these steps on the machine and under the OS account that runs the Agentrific server.

1. Install Pi

Install Node.js 22.19 or newer, then:

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

You can use either Pi 0.x or Pi 1.x to sign in. Agentrific reads the existing credentials saved by either version automatically when the server starts; you do not need to log in again or upgrade the CLI just for Agentrific. Compatibility is tested with Pi 0.87.1 and Pi 1.0.0 credential formats.

The CLI provides the login and configuration interface. Agentrific includes Pi’s runtime as a dependency and runs sessions through its SDK; you do not need to leave the Pi terminal running. See Pi’s installation guide.

2. Connect an account

Inside the Pi terminal, type:

/login

Choose a provider and follow its prompts. Pi offers the supported subscription sign-in or API-key methods for that provider. Repeat for any other accounts you want available.

You want to use	Choose in Pi	Authentication
Claude models	Anthropic (anthropic)	Pi’s Claude Pro/Max sign-in when available, or an Anthropic API key
OpenAI models with ChatGPT	OpenAI (openai)	Sign in with ChatGPT; supported by Agentrific’s Pi 1.0.0 runtime
OpenAI API models	OpenAI (openai)	An OpenAI API key
Grok models	xAI (xai)	An xAI API key
Models routed through OpenRouter	OpenRouter (openrouter)	An OpenRouter API key

Pi 0.x can store ChatGPT credentials under OpenAI Codex (openai-codex), which Pi 1.x also offers as OpenAI Codex (legacy). Agentrific recognizes these existing credentials as well as the newer openai login. Its stored connection is separate from openai; existing Agentrific sessions keep their saved connection. Choose a model on the connection you authenticated.

A subscription or key must have access to the model you select. Check the provider’s account limits and billing. Pi lists other supported providers in its authentication reference.

For a remote server, open the login link in your browser. If Pi asks for a redirect URL or authorization code, paste it into the Pi terminal on the server.

Claude and ACP

The current Agentrific integration uses Pi’s Anthropic provider for Claude models. It does not run Claude Code through ACP or launch Codex CLI. Signing into another coding-agent CLI alone does not establish Pi authentication; complete /login in Pi for the account you want to use.

3. Check model availability

In Pi, type:

/model

Confirm a model from your connected provider is selectable. You can then exit Pi. Checking the model list does not start a coding task or establish that a paid request will succeed.

Continue with choosing a phone connection and installing the Agentrific server. In Agentrific, open Settings → Default model, press Refresh and choose an available model before starting your first task.

Platform identifies the connection, such as OpenRouter. Provider identifies the model maker, such as Anthropic. A Claude model accessed through OpenRouter needs OpenRouter credentials.

Agentrific saves its own default for new runs. Choosing a default in Pi’s terminal does not change it. Existing sessions keep their selection; change a session’s reply model only while it is idle.

Credentials and background services

Pi saves login credentials in ~/.pi/agent/auth.json by default, separate from Agentrific’s database. Keep that file private. Credentials remain on the server and are never sent to clients.

Use the same OS account for pi /login and the server. Agentrific’s user service runs under your account and can use its stored Pi credentials. A terminal export is not copied into the installed service, so stored credentials are the simplest service setup.

If you change Pi’s directory with PI_CODING_AGENT_DIR, both Pi and the server must use the same value. The installed user service does not copy this variable automatically; use the default location unless you have configured the service environment separately. See Pi configuration.

API keys from the environment

For a foreground server, Pi also supports environment variables:

Connection	Variable
Anthropic	ANTHROPIC_API_KEY
OpenAI API	OPENAI_API_KEY
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY

Supply the chosen variable to the process that starts agentrific start. Stored Pi credentials take precedence over environment keys. For services, use Pi’s stored login or configure the service environment explicitly. Never paste provider keys into the client pairing form: its PIN only authorizes device access.

Troubleshooting

• Pi works but Agentrific has no models after ChatGPT login: older Agentrific releases embed Pi 0.87.1, which cannot recognize the newer openai ChatGPT login. Update Agentrific to a release with Pi 1.0.0, then refresh the model list and choose an available default. As a temporary option for the older runtime, authenticate the separate OpenAI Codex (legacy) connection and select a model from that connection.
• No available models: run /login and /model in Pi on the server, under the server’s OS account. Confirm both processes use the same Pi directory. Then refresh Agentrific’s model list.
• A model appears but cannot run: configured access is not a successful provider request. Check expired login, account access, quota and billing. Reauthenticate in Pi, then refresh. Do not restart while work is active; follow the server guide’s maintenance procedure if a restart is needed.
• Works in the terminal, fails as a service: check the service account and whether credentials were supplied only through shell environment variables. Prefer stored Pi login for the user service.
• The first task reports an unavailable default: explicitly choose an available default in Agentrific; it does not import Pi’s terminal selection.
• Need a custom or local endpoint: follow Pi’s model configuration guide for models.json, then refresh the server catalogue. Built-in providers normally need only /login.

Use Pi’s /logout to remove a stored provider credential. This does not revoke the credential at the provider or clear environment variables. See the authentication reference for credential management.