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 session lives in a git worktree.
GitHub CLI (gh)	The manager clones, pushes and manages pull requests through gh’s authentication.
Claude Code (claude)	The agent itself. The manager runs one per task as a child process and talks to it over pipes. Needs a subscription credential (Pro, Max, Team or Enterprise).

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 claude are named absolutely, and doctor resolves each of them the way the daemon will rather than the way your shell does.

Give it the two credentials

doctor will report both of these as problems, and neither 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.

Claude. The agents inherit the manager’s environment, so the subscription credential belongs to the manager’s own service definition:

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.

Installation has the detail on both.

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 claude 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 the agents will have a Claude credential, 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 session from the app and watch it work.

The tutorial walks through all of it end to end.