Advanced configuration

Start here after completing your first task. This walkthrough turns the foreground setup into a persistent installation. Keep using the same OS account and data directory so your paired devices, model credentials and task history remain available.

1. Make the HTTPS address persistent

A background server can use the bundled OpenTunnel connection or an independently managed tunnel. Services use the saved connection choice without a menu. OpenTunnel restores its saved identity and address on startup.

Wait for work to finish, then stop the foreground server with Ctrl+C. Choose one of these:

• OpenTunnel: save agentrific init --connection opentunnel. No separate tunnel process is needed; skip the manual public-address command below.
• Tailscale: configure Tailscale Serve in background mode with tailscale serve --bg http://127.0.0.1:4318. Keep Tailscale running on both the server and phone.
• Cloudflare: configure a named tunnel with a stable hostname and a persistent tunnel process forwarding to http://127.0.0.1:4318.
• Existing proxy: keep your HTTPS endpoint and its proxy process running independently of Agentrific.

Save the real HTTPS address, replacing the example hostname:

agentrific init --connection existing --public-url https://YOUR-SERVER-HOSTNAME
agentrific start --no-interactive

From a second terminal, run agentrific status and agentrific pair. Pair the phone using the stable address and check that you can open your project. An address change requires pairing again. Stop this foreground process before installing the service below.

2. Install a user service

Use a stable Node installation and the globally installed server package. The service records their paths; a temporary installation or a removed Node version will break startup.

agentrific service install
agentrific status
agentrific logs

Installation starts the service. agentrific logs follows its output; Ctrl+C exits the log viewer. Open the app and confirm it reconnects, then check that the model picker still offers your configured models.

macOS uses a LaunchAgent under your user account. Linux uses a systemd user service, whose lifetime normally follows your login; configure lingering separately if it must survive logout. A service does not keep a sleeping machine online.

The service captures PATH at installation so Git and package managers can be found. It does not copy other shell environment variables. Stored Pi credentials work when the service runs as the same user; API keys exported only in your terminal will not be inherited.

See the service reference for definition locations, restarts and uninstalling. Never run a foreground server and a service against the same data directory.

3. Choose project and storage locations

These locations serve different purposes:

Location	Default	How to configure it
Project repositories	~/projects	Server settings → Projects folder; saved across restarts.
Server configuration and state	~/.agentrific	CLI --data-dir or AGENTRIFIC_DATA_DIR. Use an absolute path.
New managed worktrees	~/.agentrific/workspaces	AGENTRIFIC_WORKTREES_DIR in the server process environment.
Pi accounts and configuration	~/.pi/agent	Pi’s PI_CODING_AGENT_DIR; Pi and the server must agree.

AGENTRIFIC_PROJECTS_DIR supplies the startup default before a Projects folder has been saved. Changing the Projects folder or worktree default does not relocate existing runs. Keep worktrees outside your project repositories and keep existing recorded paths valid.

For a new installation with a separate data directory, use that directory consistently:

agentrific init --data-dir /absolute/path/agentrific --public-url https://YOUR-SERVER-HOSTNAME
agentrific start --data-dir /absolute/path/agentrific --no-interactive

Commands such as pair, status and service install also need --data-dir /absolute/path/agentrific when targeting this installation. Choosing an empty directory creates separate state; it does not migrate your current installation.

For services, configure custom environment variables in the platform’s service environment. Exporting them before service install does not persist them. Prefer the default directories unless you need a different layout.

4. Add or change model access

Run Pi under the server’s OS account, use /login to add an account and /model to check availability. In Agentrific, refresh Settings → Default model and select the default for future runs. Existing sessions retain their choice; change a session’s reply model only while it is idle.

For environment keys, alternate Pi directories or compatible local endpoints, follow Pi and model accounts. Model credentials stay on the server. Platform is the connection you authenticate with; Provider is the model maker. A model routed through OpenRouter uses your OpenRouter access.

Before relying on changed credentials in a service, run a small task and check the response. A selectable model confirms configured access, not provider quota or a successful request.

5. Manage paired devices

Generate one invitation per device and review access from the server terminal:

agentrific pair
agentrific devices
agentrific revoke DEVICE-UUID

Replace DEVICE-UUID with an ID from the device list. Revoking a device closes its connections and blocks future requests. It does not stop agents already running. See pairing and device access.

6. Maintain, update and back up

Before a planned restart or update, prevent new work and wait for existing work to finish:

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

If drain times out, inspect the reported blockers and wait or resolve them before continuing. Maintenance remains enabled. Run agentrific maintenance resume if you decide to keep running without a restart.

Check for a release with agentrific update --check, then follow the update procedure to stop the appropriate foreground process or service, install the package and start it again. Updates are installed manually. Restarting with active runs interrupts them; inspect their transcripts before resuming.

For a consistent backup, drain work and stop the server, then back up the whole data directory, the project repositories and the managed worktrees. Include Pi’s separate configuration and credentials in a protected backup if you want to preserve model access. Copying only sessions.sqlite omits conversations and attachments. Restore with recorded paths intact before starting a single server process.

7. Enable automation when ready

Once manual tasks and service reconnection work, open automation settings, choose projects, set parallelism and save a schedule. Follow Automation for queue ordering, UTC schedules and failure recovery.

Automation requires the server to stay running. Start with a small queue and review the first scheduled run before increasing concurrency.