v1.22.52see what's new →
← Learn

Quickstart

Updated August 6, 2026

A guided path from a fresh machine to a working fleet: install the CLI, run first-time setup, add harnesses, smoke-test a team, register your devices, and write your first AGENTS.md. Every step names the exact command. Run agents <cmd> --help if anything below looks stale — the code wins over this page.

1. Install

One binary on your PATH. macOS and Linux.

curl -fsSL agi-cli.sh | sh
agents --version

npm and bun work too: npm i -g @phnx-labs/agents-cli or bun install -g @phnx-labs/agents-cli. Every command also answers to the shorter alias ag — ag view and agents view are the same call. Already installed? agents upgrade updates the CLI itself (-y skips the confirm).

2. First-time setup

agents setup is the one-time bootstrap. It clones the system config repo into ~/.agents/.system/, imports any agent CLI already on the machine, and on a terminal walks a re-runnable capability hub: browser, computer, share, secrets, fleet, watchdog, plus two preferences (which machine you sit at, which browser agents drive here).

agents setup

Each capability can also be set up on its own later:

agents setup browser    # detect a browser + create the default profile
agents setup secrets    # choose secrets backend/policy defaults
agents setup fleet      # discover Tailscale devices + configure SSH access

When a command behaves unexpectedly, agents doctor is the broader health check — it reports CLI availability, sign-in state, and resource drift, and --fix heals every gap it finds.

agents doctor            # local diagnostics + cross-device divergence
agents doctor --fix      # heal every gap it found

3. Add harnesses and log in

Install the CLIs for the agents you want to run. agents add <agent>[@version] downloads and installs it; the first version you add for an agent becomes its default.

agents add claude@latest
agents add codex@latest
agents add grok@latest

Supported ids include claude, codex, grok, kimi, antigravity, opencode, cursor, droid, and more. Run agents add --help for the option reference. To run a hosted model (Kimi, DeepSeek, Qwen) through the Claude Code runtime instead of installing its own CLI, use a profile.

Log in the way each harness natively expects — most launch their own OAuth flow the first time you run them interactively.

agents run claude   # opens Claude Code's native login on first run
agents run codex
agents run grok

Verify a harness is installed, signed in, and reachable headlessly:

agents view                                               # installed versions, accounts, usage
agents doctor claude                                      # per-agent report
agents run claude "Reply with exactly PINGOK" --mode plan  # headless read-only ping

The --mode flag sets how much the agent can do: plan is read-only (safe against anything), edit lets it write files, auto auto-approves safe operations and prompts on risky ones, skip bypasses all permission prompts. Omit the prompt for an interactive session instead of a headless one.

4. Smoke-test teams

agents teams runs several agents in parallel on one task, each optionally isolated in its own git worktree. Check who can join first, then run a minimal two-teammate team.

agents teams doctor                       # which agents are installed and ready to join

agents teams create smoke-test
agents teams add smoke-test claude "Summarize README.md in three bullets" --name reader
agents teams add smoke-test codex  "List every TODO comment in src/" --name scanner
agents teams start smoke-test --watch     # launches both, streams status live
agents teams status smoke-test            # files touched, recent commands, last messages
agents teams disband smoke-test           # stop everyone, clean up the registry entry

With only one harness signed in, point the second teammate at the same agent — teams do not require distinct harnesses, mixing them is just the common case. Teammates rotate across signed-in accounts by default. Read parallel work with teams for worktree isolation and DAG dependencies, or the teams reference for every subcommand.

5. What is a fleet?

A fleet is your own machines, reachable over Tailscale/SSH, that agi-cli can run commands on or dispatch agents to. Register them once, then target any of them with one flag.

agents setup fleet         # discover Tailscale nodes, configure SSH access
agents devices sync        # register every discovered node
agents devices list        # platform, address, reachability, live headroom

Pick the one machine that should show you rendered artifacts (a browser window, a dashboard, a plan) when an agent opens something for you to look at. This is usually the laptop or desktop you sit at.

agents devices set-interactive worker-1   # replace with your device's name
agents devices set-interactive             # print the current interactive host

Keep the machine you actually work from lighter than your worker boxes: point long-running teams and remote runs at the workers rather than piling everything onto your daily driver. See devices for the registry model and remote runs for the --host/--device dispatch flags.

6. Write your first AGENTS.md

AGENTS.md at the repo root is the harness's instructions. The agent reads it on every run. Start with four lines that capture rules you would otherwise repeat in chat.

# AGENTS.md

- Tests live next to source. No mocking.
- Use bun, not npm or yarn.
- Python: built-in type hints, loguru for logging.
- Env files: .env.dev and .env.prod. Never commit either.

When the agent gets something wrong, do not argue with it in chat. Edit AGENTS.md so the next run starts with the rule in context. One failure, one line. That is the loop. Read harness engineering next for the full pattern.

7. Where next

That is the path from a fresh machine to a running fleet. From here the same command shape scales out. Pick the thread you need: