Your first task

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

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 at least one agent engine — the Claude Code CLI, the Codex CLI, or both — 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 subscription for whichever engine you installed (Claude Pro/Max/Team/Enterprise, or a ChatGPT plan for Codex);
• your phone, with the Agentarivm app.

1. Install the manager

On the machine:

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

The installer downloads the right build and installs the agentarivm command. It is safe to re-run.

It does not write a configuration, and that is deliberate — the config is where you decide which repositories agents may touch and who is allowed to authorise them, so nothing writes it behind your back. Do it now:

agentarivm init

That prints the path it wrote and refuses to overwrite a config you already have. Every command except init reads this file, so it comes before everything below; if you skip it, the next command tells you so by name.

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

agentarivm login

Then authenticate the tools the manager drives:

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:

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

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

Tell the manager which repository agents may work in:

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>.

A repository with no .agentarivm.yml, under a profile that runs no checks, is reviewed but never built or tested. The app says so when you add one, and can have an agent propose the file as a pull request — see a repository without one.

Once your phone is paired you can do the same from the app: Projects → + adds a repository that is already on GitHub, searched by name across your account and every organisation you belong to (type owner/ to search just one), and New from idea creates one — under your account or any organisation that lets you — with your idea committed to it, and starts an agent that plans it with you and opens the issues the plan breaks into. See a plan that becomes issues.

4. Pair your phone

On the machine:

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 task from the app

In the app:

1. Open Create task.
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 task, builds the prompt, and launches the chosen engine in it. (With more than one engine configured, the form offers the choice; with one, it does not ask.) On the dashboard the task appears immediately and moves through its stages:

queued → preparing → starting → running → pr_open

6. Watch it work

Open the task’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 task at any time; its worktree and branch stay on disk for inspection.

7. Review and merge

When the task 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

A merged task cleans itself up: the work is in the base branch, so the manager stops any agent still running for it, removes the worktree and deletes the local branch without being asked. A worktree is hundreds of megabytes, and one per merge adds up fast.

It only does this when the local branch is exactly the commit GitHub merged. A task can still be running when its pull request merges, and an agent that commits a second later leaves the branch somewhere the merge never saw — so if the branch has moved on, or the worktree has uncommitted changes, the task says so on its timeline and keeps the worktree for you. Push those commits and the next cleanup goes through.

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

Neither path touches the remote, and neither touches the conversation: the timeline and the full agent transcript outlive the worktree by a year, because they are the only record of why. See retention to change that.

One consequence worth knowing: deleting the local branch after a squash merge leaves the pre-squash commits unreachable, so a review comment that cites one by SHA no longer resolves to anything you can check out. The content is in the base branch and the reasoning is in the transcript.

Where to go from here

• Let GitHub issues start tasks on their own: GitHub issue automation.
• Tune models, effort, concurrency and polling: Configuration reference.
• Understand what the phone can and cannot do: Security model.