Quickstart

From zero to your first autonomous run in about five minutes. Each step is copy-paste.

1 · Install

Pick whichever line matches your machine — ripgrep comes along with the packaged paths:

# Homebrew (macOS or Linux)
brew install section9labs/tap/rupu

# Arch Linux (AUR)
yay -S rupu-bin

# Debian / Ubuntu — .deb from the releases page (Fedora/RHEL: .rpm + dnf)
sudo apt install ./rupu_<version>_amd64.deb

# bare binary: rupu-darwin-arm64 | rupu-linux-x64 | rupu-linux-arm64
chmod +x rupu-linux-x64 && sudo mv rupu-linux-x64 /usr/local/bin/rupu

rupu --version

Every asset lives on the releases page. Nix, hosted APT/YUM repositories, and the from-source build are all in Overview & install.

Already installed? Keep it current with rupu update — it self-updates in place and keeps a backup for --rollback. Add --channel beta for early-access prereleases. If you installed through a package manager, upgrade through it instead — on a .deb / .rpm install rupu update refuses and tells you as much, and --check keeps working either way.

2 · Initialize & connect a model

init scaffolds .rupu/ in the current repo with a set of starter agents and workflows; auth login connects a model provider (credentials are written to ~/.rupu/auth.json, mode 0600).

rupu init
rupu auth login          # pick anthropic / openai / gemini / copilot
rupu auth status

See Providers & Auth for the full provider + auth-mode list — and note each agent can use a different provider, so one workflow can mix models.

3 · Run your first agent

The starter set includes a code-reviewer agent. Point it at your current diff:

rupu run code-reviewer --prompt "Review the changes on this branch"

# everything is recorded as a JSONL transcript
rupu transcript list
rupu transcript show <run-id>

An agent is just a Markdown file (config in YAML frontmatter + a system prompt). Open .rupu/agents/code-reviewer.md to see one — full format in Agents.

4 · Run your first workflow

Workflows compose agents into steps. review-changed-files (bundled by init) fans a reviewer across every changed file in parallel, then summarizes:

rupu workflow run review-changed-files \
  --input files="$(git diff --name-only main...HEAD)"

List what's available with rupu workflow list. More shapes — sequential hand-offs, parallel review panels with gated fix-loops — in Workflows and Examples.

5 · Open the Control Plane

Prefer a browser? Launch the local web command center to author, launch, watch, and approve runs — including the drag-and-drop visual workflow editor:

rupu cp serve           # opens http://127.0.0.1:7878

Tour of every surface in Control plane.

6 · (Optional) Add a host

Drive rupu on another machine from this same Control Plane. On the remote, serve the API; on your machine, register it:

# on the remote machine (behind TLS)
rupu cp serve --bind 0.0.0.0:7878 --token "$RUPU_HOST_TOKEN" --no-open

# on your machine
rupu host add gpu-box --url https://gpu.internal --token "$RUPU_HOST_TOKEN"
rupu host list

Then pick the host in the launcher. See Multi-host.

7 · (Optional) Install the security fleet

Doing security work? rupu ships a stock fleet of assessment agents and workflows, one set per engagement profile. Install it into ~/.rupu and run one against a target you’re authorized to test:

rupu fleet install
rupu workflow run network-assessment --engagement-profile network \
  --input scope="10.0.5.0/28"

What it ships, and how to drive it from an agentiflow lead: The stock security fleet.

8 · (Optional) Connect Claude Code over MCP

The control plane you started in step 5 also serves an MCP endpoint at /mcp, so an agent in Claude Code (or Cursor, or Claude Desktop) can launch workflows, watch runs, approve gates and message a live run itself. Point Claude Code at it:

# rupu cp serve without a token (loopback, the default)
claude mcp add --transport http rupu http://127.0.0.1:7878/mcp

# if you started it with --token, pass the same token
claude mcp add --transport http rupu http://127.0.0.1:7878/mcp \
  --header "Authorization: Bearer $CP_TOKEN"

claude mcp list      # shows whether it connected

rupu cp serve prints this command at startup. The MCP gives the client the same reach as the control plane's operator — rupu adds no permission layer of its own there, so narrow it with --tools if you want less. Every tool, the wait loop and the other clients are in MCP & tools.

Where to next