Project setup

A brand-new git worktree is a clean checkout: no node_modules, no .env, nothing that isn’t committed. These settings are how you tell Astra what a usable copy of your project needs. Find them under Settings › .

They apply to worktree spaces, which are the ones that get a fresh checkout. Local spaces run in the folder you already set up.

Setup command

A shell command run in a new worktree after it’s created, before the agent starts. Almost always a dependency install.

Astra prefills this from the lockfile it finds when you add the project:

Lockfile	Prefilled command
pnpm-lock.yaml	pnpm install
yarn.lock	yarn install
bun.lockb	bun install
package-lock.json	npm install

That’s the whole of the detection — a lockfile is unambiguous evidence. Astra won’t infer a build step or run a script it guessed at. Edit the command to whatever your project actually needs, chain steps with &&, or clear it if there’s nothing to do.

If setup fails, the space says which step failed and why. It doesn’t start the agent on a half-provisioned checkout.

Seeded files

Files copied into every new worktree. These are the gitignored ones a fresh checkout can’t have but your app needs to run — .env and friends.

Astra prefills this list with gitignored .env* files at your repo root. Add or remove paths as needed.

Two things follow from seeds being Astra-managed rather than yours:

• They’re copied from your main checkout each time, so a worktree always gets your current values.
• They’re excluded from the work-in-progress capture on archive, so secrets never end up in the git object store and a reopened space gets fresh copies rather than stale ones.

Teardown command

A command run in the worktree just before it’s removed, on archive or delete. Use it for anything that outlives the folder — stopping a container, freeing a port, dropping a scratch database. Leave it empty if there’s nothing to undo.

Run command

The build-and-launch command behind the Run button in a simulator tab. Set it and the button appears; leave it unset and there’s no button. Astra keeps one run terminal per checkout and reuses it, so switching away from a space and back reattaches to the running app instead of starting it again.

Home branch

Each project has a home branch — the ref new worktree branches start from and pull requests merge back into. It’s read-only in Astra: the value comes from the repo’s remote, so it’s whatever GitHub says your default branch is. A repo with no remote shows its local default instead, that being the only truth available.