Guide / Getting Started / Your First Multi-Agent Run: From Install to Dispatch in 5 Minutes
← All Articles
Getting Started

Your First Multi-Agent Run: From Install to Dispatch in 5 Minutes

From connecting your first machine to running an approved spec across a natural-language agent fleet — the full first-run path through Jerico in one walkthrough.

On this page

What you'll have running

By the end of this walkthrough: a connected machine, a workspace with a real project, an agent fleet spawned in plain language, one spec run through planning and approval, and a project blueprint you can keep current with one approval. Every step below links to a deeper article — read this one straight through first, then go back for detail on whichever step you need.

Before you start

  • A Jerico account and a workspace (sign up at jerico.appnova.io if you haven't already).
  • At least one supported CLI agent installed on the machine you want to connect (e.g. claude, codex, qwen, opencode) — Jerico detects and drives your existing installs, it doesn't install agents for you.

Step 1 — Connect a machine

  1. Download Jerico for Mac and open it.
  2. In the web app, go to Settings → Connected Machines → Add machine (or open /connect directly). Enter a machine name and click Generate token.
  3. Paste the token into the app. The bundled daemon starts automatically — no terminal required.

Jerico runs on macOS 12 or later. Linux and Windows builds aren't available yet, so the Mac app is the only way to connect a machine today — there's no separate CLI install to run.

Back in Settings → Connected Machines, your machine shows as connected.

Step 2 — Create a workspace and project

Click the + New Project button on the workspace welcome screen, enter a Project Name, select the Machine you just connected, and point it at a local codebase directory. Click Create Project — no custom setup scripts or folder wrangling required. → Full detail: Create Your First Workspace and Project.

Step 3 — Spawn an agent fleet with natural language

In the orchestrator input bar, describe what you need in plain language (e.g. create a claude developer, codex developer and an opencode developer) instead of creating panels one by one. The orchestrator issues one spawn request per panel you asked for, each validated against the target daemon — panels appear as each one completes, not all in one instant. → Full detail: Spawn an Agent Fleet with Natural Language.

Step 4 — Run a spec through planning, approval, and dispatch

Enter your feature request or spec in the orchestrator prompt bar. Jerico's server-side planner breaks it into a dependency graph (DAG) of todos and sends the plan to your browser. Review the read-only plan, then choose Approve & Run or Cancel for the whole plan — there's no per-todo edit at this gate. Once approved, ready todos dispatch to free panels matching each todo's role. → Full detail: Run a Spec Through Planning, Approval, and Dispatch.

Step 5 — Keep the project blueprint current

As agents finish real work, the orchestrator offers to write confirmed architectural decisions and conclusions back into the project's blueprint — it only updates after you approve — so your next session starts from the real current state instead of a stale one. → Full detail: Keep the Project Blueprint Current.

That's it

Connect → workspace → fleet → spec → blueprint. That's the whole loop: one connected machine feeding a project, one natural-language fleet doing the work, one approved spec turning into dispatched todos, and one blueprint you can keep true with a single approval after each run. Every other article in this guide is a deeper look at one part of this loop.

If it fails

  • Machine doesn't show as connected — check the Jerico app's menu-bar icon for its connection state, confirm the app is actually running, and that the token hasn't been revoked from Settings → Connected Machines.
  • Agent panel won't spawn / "binary not found" — the daemon only detects agents already installed and on PATH for the account the app runs as; install the CLI first, then reopen the panel.
  • 401/token errors during auth — tokens are single-purpose per daemon identity; generate a fresh one from Settings → Connected Machines → Add machine rather than reusing an old value.

How it works

The daemon runs locally next to your AI agents and holds the real PTY sessions; the browser sees a relayed WebSocket stream. Jerico's server also handles auth, orchestration/planning (including spec decomposition), run state, and a bounded transcript of completed todo output — it's more than a passthrough. The CLI agents themselves still send prompts and code to their own model providers under your own credentials, the same as running them directly in a terminal.