# One branch per task

> Run agents in parallel, each in an isolated environment.

Give every agent task its own branch: a copy-on-write database with the parent's data, a forked bucket, and a running copy of the app at its own URL. A branch's resources are fully separate — its own connection string, bucket, and machines — so work an agent does *on its own branch* never reaches `main` or another agent's branch. The branch boundary is separation: any command that accepts `--branch` can still reach another branch when you tell it to, so the isolation comes from agents working on their own branch by default.

## Why branches

An agent that shares an environment with you — or with another agent — can corrupt data or race migrations. A branch removes that class of problem:

- **Real data, zero risk.** The branch's Postgres opens with the parent's data. Broken migrations and bad writes stay on the branch.
- **A live URL from the start.** Branch compute comes up running the parent's image, so the agent can see the app working before its first deploy.
- **Disposable.** When the task is done, delete the branch. Ten branches per project caps how far a fleet can sprawl.

## The workflow

Per task, the agent runs these itself if it has the `insta` skill:

```bash
insta branch create task-auth-refactor
insta branch switch task-auth-refactor
insta secrets
insta deploy .
```

`insta branch create` forks from your current branch (choose explicitly with `--from`). After `switch`, every CLI command — `secrets`, `db url`, `run`, `deploy` — targets the branch automatically. MCP agents pass `branch` explicitly instead; they have no linked directory.

## Promote and clean up

Promotion is a migration, not a copy:

1. Merge the agent's code branch in git.
2. Run the migration files against `main`'s database.
3. `insta branch switch main`, then `insta deploy .`.
4. Delete the branch:

```bash
insta branch delete task-auth-refactor
```

`insta branch merge <source> --into main` creates any service the branch added as an empty service of the same type and name on the target — deploy to it afterwards; data never merges. Audit what the agent did at any point with `insta agent events`.

<Note>
On self-hosted InstaCloud OSS, a merged compute group is created **and deployed** with the source branch's image, against the target's own database and bucket — an agent-built image can go live on `main` through merge alone.
</Note>