Skip to content
Agentarivm
Alpha — private preview. Expect rough edges and breaking changes between releases.

Your first session

This walkthrough takes a fresh machine to a merged pull request: install the manager, register a repository, pair your phone, create a session from the app, watch it work, and merge the result. Budget half an hour, most of it watching an agent code.

Before you start

Section titled “Before you start”

You need:

  • a dedicated machine (Mac or Linux) that stays on — see Getting started for the platform list;
  • git, the GitHub CLI (gh) and the Claude Code CLI installed on it;
  • a GitHub account with push access to a repository you want agents to work in — ideally a test repository for this first run;
  • a Claude subscription (Pro, Max, Team or Enterprise) for the agent;
  • your phone, with the Agentarivm app.

1. Install the manager

Section titled “1. Install the manager”

On the machine:

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

The installer downloads the right build, installs the agentarivm command, and writes a starter configuration at ~/.config/agentarivm/agentarivm.yml if none exists. It is safe to re-run and never overwrites a config you already have.

Sign in to your Agentarivm account — it prints a URL and a code; approve in any browser with GitHub:

Terminal window
agentarivm login

Then authenticate the tools the manager drives:

Terminal window
gh auth login                                # the account the manager will act as
claude setup-token                           # then paste it into:
pbpaste | agentarivm agent-token install     # reads from stdin only — never an argument

Now let the machine tell you what is still missing:

Terminal window
agentarivm doctor

Fix anything it lists and re-run until it exits clean. doctor checks the machine the way the daemon will actually use it — including the PATH its subprocesses get, which is the most common thing to be wrong.

2. Start the manager and keep it running

Section titled “2. Start the manager and keep it running”
Terminal window
agentarivm service install
agentarivm service status

On macOS this installs a launchd LaunchAgent; on Linux, a systemd user unit (enable loginctl enable-linger on a headless box). The service restarts the manager if it crashes and starts it at login.

Make sure the config has a server.publicUrl your phone can reach and TLS on (tls.mode: managed) — see the configuration reference. After changing the config, agentarivm service install again to reload.

3. Register a repository

Section titled “3. Register a repository”

Tell the manager which repository agents may work in:

Terminal window
agentarivm project add your-name/your-repo

The manager clones it under its gitRoot and records it. Repositories are an explicit allowlist — the app can only ever choose from this list, never submit a path. agentarivm project list shows what is registered.

If the repository needs setup before an agent can work (dependencies, env files), attach a setup profile with --profile <name>.

4. Pair your phone

Section titled “4. Pair your phone”

On the machine:

Terminal window
agentarivm pair --name "My iPhone"

A one-time pairing code appears — scan it as a QR code from the app’s Pair screen. The phone receives its device token and a client certificate; from now on it talks to the manager over mutual TLS. Details in Pairing your phone.

agentarivm devices list should now show your phone.

5. Create a session from the app

Section titled “5. Create a session from the app”

In the app:

  1. Open Create session.
  2. Pick the repository you registered.
  3. Describe the task. Be concrete: a goal, acceptance criteria, and how to verify — the same things you would put in a good issue.
  4. Choose a model and effort from the allowed lists, confirm the base branch, and start.

The manager cuts a branch, creates a dedicated git worktree for the session, builds the prompt, and launches Claude Code in it. On the dashboard the session appears immediately and moves through its stages:

queued → preparing → starting → running → pr_open

6. Watch it work

Section titled “6. Watch it work”

Open the session’s detail screen. As the agent works you’ll see:

  • a progress timeline — lifecycle stages, plus reports the agent sends from inside the worktree;
  • commits and changed files, as they land;
  • the pull request the moment it opens, with CI checks as they run.

The agent commits as it goes, pushes its branch, and opens a draft pull request — it is explicitly forbidden from merging. You can stop a session at any time; its worktree and branch stay on disk for inspection.

7. Review and merge

Section titled “7. Review and merge”

When the session reaches PR open:

  1. Review the diff — in the app’s changed-files view, or on GitHub; the pull request is a perfectly normal one.
  2. Mark ready turns the draft into a reviewable pull request.
  3. Merge — behind a biometric confirmation. The manager re-reads the pull request from GitHub immediately before merging: if checks fail, conflicts appeared, or the agent pushed another commit after you looked, the merge is refused with the reason, so the thing merged is always the thing you reviewed.

8. Clean up

Section titled “8. Clean up”

A finished session keeps its worktree and local branch — that is why a failed session can still be inspected. When you are done with it, the app’s cleanup action shows a checklist of preconditions (session finished, every commit safely on the remote, nothing uncommitted) and then removes the worktree and local branch. It never touches the remote.

Where to go from here

Section titled “Where to go from here”