Getting started

What you need

Agentarivm expects a dedicated, always-on machine — a Mac mini in a closet, a Linux box, a home server. It is a control plane for coding agents, so treat the machine as one: ideally its own user account, used for nothing else.

On that machine you need:

Tool	Why
git	Every task lives in a git worktree.
GitHub CLI (gh)	The manager clones, pushes and manages pull requests through gh’s authentication.
At least one agent engine	The agent itself, run as a child process. Claude Code (claude) needs a subscription credential (Pro, Max, Team or Enterprise); Codex (codex) needs a ChatGPT plan or an OpenAI API key. Install both if you want one engine reviewing the other’s work.

Supported platforms: macOS (Apple Silicon and Intel) and Linux (x64 and arm64). On Windows, run Agentarivm inside WSL2.

Install

curl -fsSL https://agentarivm.com/install.sh | sh

The installer detects your platform, downloads the matching release, and installs the agentarivm command. It is safe to re-run and never overwrites an existing configuration. Prefer manual installation? See the download page and the installation guide.

Write a configuration

agentarivm init

This writes ~/.config/agentarivm/agentarivm.yml with sensible defaults and tells you what to edit. Every command below needs it — the manager validates its configuration at boot and refuses to start half-configured, so there is nothing to run until this file exists.

It never overwrites a config you already have; --force does, if you mean it.

The paths worth checking before you go on are the executables. A service gets a minimal PATH — no /usr/local/bin, no nvm, no ~/.local/bin — so git, gh and every engine’s binary are named absolutely, and doctor resolves each of them the way the daemon will rather than the way your shell does.

Give it its credentials

doctor reports each of these as a problem until it is done, and none of them is something the installer can do for you — each is an account you own.

GitHub. Authenticate as the identity the manager should act as; everything it does on GitHub happens under this one.

gh auth login

Pin it with github.expectedAccount in the config, so a wrong login is refused at boot rather than doing everything perfectly under somebody else’s name.

The agent engines. Each engine you configure needs its own credential, and the agents get them from the manager rather than from your shell.

Claude Code, whose credential is read from stdin and never from an argument:

claude setup-token
pbpaste | agentarivm agent-token install     # stdin only; never an argument

It refuses an sk-ant-api… API key on purpose — an API key bills pay-as-you-go credits and outranks the subscription token in Claude Code’s own precedence, so installing one is worse than installing nothing.

Codex, if you run it, has two doors. Prefer the subscription: it spends plan quota rather than metered credits, and it is a device code you enter in any browser, which is what makes it work on a headless machine.

agentarivm engine-login codex                            # ChatGPT plan
pbpaste | agentarivm agent-token install --engine codex   # or an OpenAI API key

When both exist the login wins, and doctor says so rather than leaving you to find out from a bill.

Installation has the detail on all of them.

Sign in

agentarivm login

This prints a URL and a short code; open the URL in any browser, enter the code, and sign in with GitHub. Every plan uses a free account — pricing explains what each covers. The account token is stored on the machine (mode 600) and being offline later never blocks a restart: the manager caches a signed entitlement and checks in roughly once a day.

If it answers license.publicKey is not configured, so there is nothing to sign in to, this build is not tied to a licensing service and there is nothing to do — everything else works exactly the same.

First run

Check the machine before anything else:

agentarivm doctor

doctor verifies every precondition the manager has: that git, gh and every configured engine’s binary resolve the way the daemon will resolve them (not the way your shell does — see Troubleshooting), that gh is authenticated as the expected account, that each engine has a credential and which one it would spend, and that the configured paths exist. It exits non-zero listing every problem it finds, and it deliberately creates nothing — a diagnostic that provisions what it checks for cannot report that it was missing.

When doctor is clean, start the manager:

agentarivm serve

The configuration lives at ~/.config/agentarivm/agentarivm.yml (override with --config or $AGENTARIVM_CONFIG). See the configuration reference for what goes in it.

For anything longer than a test drive, run the manager as a service so it survives crashes and logins:

agentarivm service install

See Installation for how that works on macOS (launchd) and Linux (systemd).

Then

1. Register a repository with agentarivm project add owner/repo.
2. Pair your phone.
3. Create a task from the app and watch it work.

The tutorial walks through all of it end to end.