Documentation menu

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:

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:
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.

View as Markdown