Skip to main content
A branch is a full, isolated clone of your environment. Every project starts on main; a branch forks from a parent and lives until you delete it. Use branches for staging, per-agent tasks, and per-pull-request environments.

​
What gets cloned

On self-hosted InstaCloud OSS, a branch is a fork on disk: the Postgres data directory and every compute volume are reflink-copied, so branch create returns in about a second whatever a sleeping database weighs, and the bucket objects are synced. A database that is awake is streamed with pg_basebackup instead, in time proportional to its size, because a file-level copy of a live server is not consistent. Compute volumes have no such streaming path, so they are copied whether the app is running or not: stop the group first if you need a quiescent copy.

​
Creating and switching

create forks from your current branch. Choose the parent explicitly with --from <branch>. Creating does not switch you: switch rewrites the directory link (.insta/project.json), after which every command targets the branch. Rerun insta secrets to refresh .env.

​
Branch URLs and credentials

Each branch’s compute services get their own URLs, printed on deploy and listed by insta agent manifest. Credentials are per-branch: insta postgres url prints the branch’s connection string, and the branch’s copied bindings point at the branch’s own services, so work done on a branch stays on that branch. Commands that accept --branch (secrets, deploy, storage delete, and others) can still reach another branch when you tell them to.

​
Merging

Merging is structural and additive: a service that exists on the source but not the target is created there, empty, so deploy to it afterwards. Data never merges: promoting data changes means running your migrations against the target and deploying. Existing services are skipped with a reason (exists, cap). 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.

​
Limits

  • 10 branches per project.
  • Names: lowercase letters, digits, and dashes, up to 39 characters, starting with a letter or digit.

​
Deleting

Tears down the branch’s database, bucket fork, compute, and secrets.