# Swarm — many agents, one command

> Fan out dozens of agent microVMs on prepaid Spot credits, dispatch a task to the whole swarm, and collect every result — setup, dispatch, collect.

Part of the jurniti developer docs — canonical page: https://www.jurniti.com/docs/swarm · full docs index: https://www.jurniti.com/docs/llms.txt

## What a swarm is

A swarm is many agent microVMs doing the same kind of work at once. You bring up
`N` agents with one command, send the whole cohort a task with one command, and
pull back every result with one command — then pay for exactly the minutes they
ran, out of a prepaid credit balance.

It runs on the [**Spot** usage tier](/docs/usage-tiers): half-price,
interruption-tolerant compute — the right economics for a burst of short-lived
agents that all finish and go away.

> **Still no free tier:** A swarm spins up real Firecracker microVMs. A card must be on file and you top up credits before anything runs — there's no free trial and no free tier. What you get is per-second billing and a burst you can walk away from, not a giveaway.

The shape is always three phases: **Setup → Dispatch → Collect.**

## 1. Setup — prepay, then fan out

Top up credits (your card is never charged until you do), then bring up the
swarm. `--count N` fans out `N` Spot agents in one call, and `--group` saves them
as a named cohort so every later command can drive them as one:

```bash
jurniti credits buy 20
jurniti up --tier spot --harness hermes --count 50 --group demo
```

Watch them come up in a second terminal:

```bash
watch jurniti vms ls
```

> **A group is just a local name for your swarm:** `--group demo` remembers the cohort's agent ids on your machine (under `~/.jurniti/groups`). It's a client-side convenience — the platform still confines every command to VMs your own account owns.

## 2. Give the swarm its key (auth at scale)

Each hermes agent reaches a model through **one** OpenRouter key. Write it to
every agent in the group with a single command — this is BYOK, so the key lands
encrypted inside your VMs, is never stored in our database, and is never echoed
back to your terminal:

```bash
jurniti env set --group demo --no-restart OPENROUTER_API_KEY=sk-or-...
```

> **Use an API key, not an interactive login:** Authenticate the swarm with a **model API key**, never by logging an agent into a consumer account. One key, injected into every VM, is what makes a swarm authenticate at scale — and it keeps you inside each provider's terms.

## 3. Dispatch — one task, the whole swarm

`jurniti run` hands a **task** (a prompt) to an agent. The platform builds and
runs the agent's headless command for you — you send a task, never a script — and
each agent writes its answer to `/work/out.txt`. With `--group`, the task goes to
every agent in the cohort **concurrently**, so the swarm's wall-clock is the
slowest single agent, not the sum:

```bash
jurniti run --group demo "Write a punchy one-line launch headline for a developer tool."
```

It reports how many agents succeeded and how many failed.

### Give each agent a different task (templating)

A swarm is most useful when every agent does *varied* work, not 50 copies of one
prompt. Put a `{placeholder}` in the task and fill it per-agent with `--var`:

```bash
jurniti run --group demo \
  --var audience=developers,designers,founders,marketers \
  "Write a punchy one-line launch headline for a {audience} tool."
```

Each agent gets its own prompt — one per value, mapped across the swarm in the
group's stable order. Rules:

- **`--var KEY=v1,v2,…`** provides the values; repeat `--var` for more
  placeholders (all lists must be the same length, zipped one row per agent).
- **`--var KEY=@file.txt`** reads one value per line — the easy way to feed 50
  distinct values to 50 agents (an "array" from a file).
- Fewer values than agents **cycle** (3 audiences across 9 agents = 3 each);
  more values than agents is an error (surfaces the mismatch).
- **Built-in tokens** need no `--var`: `{index}` (0-based), `{n}` (swarm size),
  `{vm}` (the agent's id). So `"Summarize shard {index} of {n}."` just works.
- A misspelled `{placeholder}` fails **before** anything dispatches (no agent
  runs a half-filled prompt). Write `{{` / `}}` for literal braces.

> **Coming next: generate the variations:** Today you supply the values. A future `--template generate` will let an agent *produce* the per-agent variations from a seed prompt — one step up the same ladder.

## 4. Collect — every result, one folder

`jurniti cp` copies a file out of your VMs. With `--group` it fans the whole
swarm's output into a local directory, one file per agent:

```bash
jurniti cp --group demo /work/out.txt ./out
```

Now `./out/` holds one file per agent (`<agent-id>-out.txt`) — the entire swarm's
work, collected.

## 5. The receipt

The meter only ran while the agents did. See exactly what the burst cost:

```bash
jurniti credits history
```

> **Why it's cheap:** Spot is **$0.025/hour**, billed **per second** with a 60-second minimum per run, and a stopped agent burns nothing. A swarm of short tasks bills like a swarm of short tasks — and a **$0 balance gracefully stops every usage VM** (persist preserved), so the burst can never overrun your top-up.

## The whole thing

```bash
jurniti credits buy 20
jurniti up --tier spot --harness hermes --count 50 --group demo
jurniti env set --group demo --no-restart OPENROUTER_API_KEY=sk-or-...
jurniti run --group demo "Write a punchy one-line launch headline for a developer tool."
jurniti cp --group demo /work/out.txt ./out
jurniti credits history
```

Fifty agents, one task each, every result on your disk — and a receipt.

> **Let your own agent run the swarm:** Every verb here is also an MCP tool. Mount the CLI once and your own agent can spin up, dispatch, and collect a swarm as tools — see [MCP](/docs/mcp).