> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run many agents in parallel

> Set up one machine, copy it, give an agent in each copy a different approach to the same task, and keep the best result.

When a task has more than one plausible solution, you can let several agents try at the same time
and keep the result that works best. You set up one machine with the repo and its dependencies, copy
it into a few machines, and send each copy its own prompt. Every copy starts from the same disks, so
the setup runs once.

This guide uses Claude Code with an Anthropic key saved as a Secret. To save the key, see the first
step of [Run a coding agent on your repo](https://instabox.sh/docs/use-cases/coding-agents.md).

**1. Set up one machine**

Create the machine that the copies are made from, and select the key's Secret for it.

```bash theme={null}
instabox create --name base --secrets ANTHROPIC_API_KEY
```

Go to your repo's folder on your computer. On this page, `my-repo`, `npm ci`, and `npm test` stand
for your own repo and its commands.

```bash theme={null}
cd my-repo
```

Push the folder to the machine. Because you give no destination, the folder lands in
`/data/home/my-repo`.

```bash theme={null}
instabox push base .
```

Then install the dependencies in the machine, so that every copy already has them.

```bash theme={null}
instabox exec base --cwd /data/home/my-repo -- npm ci
```

`push` copies your files without the `.git` folder. Start a git repository in the folder on the
machine, so that you can see later what each copy changed.

```bash theme={null}
instabox exec base --cwd /data/home/my-repo -- \
  'git init -q && git add -A'
```

**2. Copy it**

Copy the machine into three new machines. One command can make up to 5 copies.

```bash theme={null}
instabox fork base --name try --count 3
```

This command makes `try-1`, `try-2`, and `try-3` and waits until they run. Each copy has the
source's disks, size, and Secret selection, and the source machine is not changed.

**3. Give each copy a prompt**

Send a different approach to each copy. `agent prompt` starts Claude Code as a background job in
the machine and returns, so the three agents work at the same time.

```bash theme={null}
instabox agent prompt try-1 --cwd /data/home/my-repo \
  "Make the slow search test pass by adding an index."
```

```bash theme={null}
instabox agent prompt try-2 --cwd /data/home/my-repo \
  "Make the slow search test pass by caching results."
```

```bash theme={null}
instabox agent prompt try-3 --cwd /data/home/my-repo \
  "Make the slow search test pass by rewriting the query."
```

Each command prints the ID of the conversation that it started. To see whether an agent is still
working, list the conversations of its machine.

```bash theme={null}
instabox agent ls try-1
```

You can also watch one agent work. This command follows its events until the turn ends.

```bash theme={null}
instabox agent events try-1 -f
```

**4. Compare the results and keep one**

When the agents are idle, look at what each copy changed and whether its tests pass. This command
does both in `try-2`.

```bash theme={null}
instabox exec try-2 --cwd /data/home/my-repo \
  -- 'git diff --stat && npm test'
```

You can also copy a result to your computer to compare it there. This command copies the `dist`
folder of `try-2` to `./dist-b`.

```bash theme={null}
instabox pull try-2 /data/home/my-repo/dist ./dist-b
```

**5. Clean up**

Delete the copies that you do not keep. `--yes` skips the question that `rm` asks first.

```bash theme={null}
instabox rm try-1 --yes
```

```bash theme={null}
instabox rm try-3 --yes
```

## Run a script in each copy instead

A copy can run any command, not only an agent. To compare builds, benchmarks, or migrations, start
a different script in each copy as a background job.

```bash theme={null}
instabox exec --background try-1 \
  --cwd /data/home/my-repo -- ./approach-a.sh
```

To see whether the job is running or has exited, list the machine's jobs.

```bash theme={null}
instabox jobs ls try-1
```

## Limits

* Each copy is a machine, so it counts toward your plan's machines and machine starts a minute.
  Before you raise `--count`, see
  [Fork many machines at once](https://instabox.sh/docs/machines/fork.md#fork-many-machines-at-once).
* A paused machine cannot be forked, so resume it first. [Limits](https://instabox.sh/docs/machines/fork.md#limits) on the Fork
  page lists the other cases.
* A fork copies a machine now. To start copies later, or more than 5 at a time, save a
  [snapshot](https://instabox.sh/docs/machines/snapshots.md) and create each machine from it.

> [card] [Fork](https://instabox.sh/docs/machines/fork.md)
>
> What a copy gets from its source, and when a fork is refused.

> [card] [Run a coding agent on your repo](https://instabox.sh/docs/use-cases/coding-agents.md)
>
> Keys, prompts, and steering for one agent.
