Repository Setup
A git repository’s board has two buttons next to Actions and the Icebox: Setup and Run. They install and start the apps of the main checkout, the folder you opened as the workspace. A worktree has a setup of its own, see Worktree Setup.
Two ways in
Section titled “Two ways in”The first press opens Repository Setup with two choices:
- It already runs here: add the commands that start your apps.
- Set it up: say what a fresh clone needs before it runs, by hand or with an agent.
Nothing is saved or installed until you say so.
Commands that install what the checkout needs, in order, in one shell that starts in
the repository’s root: npm ci, uv sync, bundle install. Watch lists files whose
change means the setup should run again, such as package-lock.json. When one changes,
the Setup button says so, and its popover runs the setup to catch up.
One entry per app, each with a name and its Start steps; the last one keeps running.
Optional Stop steps end what Start left running outside the terminal, such as
docker compose stop. The Run button starts the app and shows its terminal and port;
with several entries, its popover lists them.
The main checkout has a port window of its own, like every worktree, so its apps take
$OFFSITE_PORT and run next to the worktrees’ apps. Setup and Run get
OFFSITE_PORT_BASE, OFFSITE_PORT_BASE_END and OFFSITE_SOURCE_CHECKOUT, and each run
entry its OFFSITE_PORT variables, as listed on
Run apps side by side. The main checkout’s
agents and terminals keep their environment as it is.
Set it up with an agent
Section titled “Set it up with an agent”Choose an agent… in the dialog starts an agent in the main checkout. It works in this folder on this host: it installs dependencies, may download build tools into the project and starts each app once to check it. It leaves tracked files alone, does not commit and does not install system tools. Its proposal fills the form, with the files it changed listed, and its summary names what it could not start here and what that needs.
Saving
Section titled “Saving”Save keeps the setup on this host, and the Setup and Run buttons use it right away. When a saved change removes an app that is running, the dialog says so first, for example web is running and will be stopped., and saving stops it.
Write to repository puts the setup into .offsite/worktree.json under main, next to
the worktrees’ part, so teammates get the same buttons. The file format is on
Worktree Setup.
A Worktree Setup can start from this one: Start from the repository setup in the Worktree Setup copies the commands and apps over.