Skip to main content
A setup is a saved machine that new sessions start on. It holds your repositories, already cloned, and whatever your setup script installed, so a session is ready in about a second. To copy one session, transcript included, fork it instead. To add a repository to a single session, use the repos chip on the home screen.

​
Which machine should a session start on?

Every session gets its own machine. You choose what’s on it when you start the session.
Not sure? If you’ve installed the same dependencies in more than two sessions, save them as a setup.

​
Create a setup

Fill in the form yourself, or ask the agent to save the session you’re in. Either way the setup is yours alone until you share it. Your own setups are limited to 5 per account.
1

Open the Setups manager

Choose Account menu → Setups (the account menu opens from your account badge at the bottom of the sidebar), or click Manage setups → in the home screen’s setup chip. Then click New setup.
2

Name it and add your repositories

Give the setup a name your team will recognise, such as harbor dev. Under Repositories, type owner/repo or paste a github.com URL, add a branch if you don’t want the default, and click Add. Private repositories need GitHub connected.
3

Write the setup script

Put the commands you’d otherwise run at the start of every session in Setup script: installs, builds, migrations, seed data. It runs once, at build time, in /workspace. The first command that fails stops the build.
4

Add a boot script and notes

Both are optional. A Boot script catches each new machine up with your repository, usually with a git pull. Notes for the agent tell it how the project runs. To share the setup, add emails under Shared with.
5

Click Save & build

Alpha opens the build log and streams it live. Save keeps the setup without building it. When the build finishes, a check mark appears under the log: “Ready — pick it on the home screen with the chip.” The setup chip’s icon sits before the word “chip”.
If you don’t see Shared with, sharing isn’t turned on for your Alpha. It needs everyone to sign in with their own account.

​
Start a session from a setup

The setup chip sits in the home composer’s bottom row, beside the repos chip. It reads blank machine until you pick a setup. This browser remembers your pick for later sessions.
1

Pick the setup

Click the setup chip and choose a setup. Setups marked building or not built can’t be picked yet. Once you’ve picked one, the repos chip lists the setup’s repositories marked “from the setup”, so you don’t add them twice.
The Setup popover open above the home composer, whose setup chip reading blank machine is highlighted. The header reads SETUP, with Manage setups → on the right. The only row is Blank machine, with a default badge and a check mark, described as Ubuntu with the agent, Node, Python, a parked PostgreSQL and a headless browser. Nothing cloned. Under it, beside two dashed squares, an empty state reads No setups yet. Add one — your team's repository, cloned and installed once, ready every time. The footer reads A setup boots with its repositories already cloned and its setup script already run — nothing to install at session start. Behind the popover, the Alpha lockup, the greeting Still up, Alex? Same. Wha… and the composer's placeholder Describe what to build — / for commands, @ for f… show at the left.

With no setups yet, Blank machine is the only choice.

2

Send your first prompt

While the machine starts, the status line reads “Starting a machine from harbor dev”.
3

Check the header

The session header names the setup beside the title for the life of the session. If the setup is later deleted, the badge reads deleted setup.
Each session starts on its own copy, so nothing you do in one session reaches the setup or other sessions.

​
Keep a setup current

A setup’s repositories are frozen at the moment it was built. There are two ways to bring them forward. A rebuild never touches existing sessions; they keep their machines. If a rebuild fails, the previous build stays in use. Resetting a session started from the setup gives it the latest build. The boot script runs on a fresh machine only, never when a sleeping session wakes. Your first message waits for it, so keep it to seconds. If it fails, Alpha notes it in the transcript, continues on the machine as built, and leaves the output in /var/log/forge-boot.log. To stop a build, click Cancel on its row or Cancel build in its log. Deleting a setup asks “Delete the “harbor dev” setup and its snapshot? Sessions started from it keep their machines.”

​
Share a setup

Add an account’s email under Shared with and click Save. The setup appears in that person’s manager and setup chip, marked “Shared by” and your name. Alpha doesn’t notify them. Removing an email takes effect at once. Sessions already started keep their machines, but their next fresh machine starts blank, with the repositories cloned again. Setups shared with you don’t count toward your limit of 5 per account.
Starting from someone else’s setup means trusting them. Its boot script runs as root on your new machines with your GitHub token and secrets in its environment, and its owner can change that script at any time without a rebuild.

​
What a build keeps and what it removes

A build never touches your sessions. Alpha starts a separate, temporary machine, lends it your credentials, runs your setup, removes the credentials and saves the result. Only the environment is cleaned, not files. A token your script writes into .npmrc or .env ships to everyone you share the setup with. Keep keys in secrets and read them from the environment.

​
What do the statuses and messages mean?

Builds are limited to 30 minutes (default), and two run at a time across your Alpha. Other start-up errors are in Troubleshooting.

​
Next steps

Connect GitHub and add repositories

Connect an account so setups can clone your private repositories.

Secrets

Store the keys your setup script needs, so they never land in a file.

Sleep, wake and reset

What a reset does to a session that started from a setup.

Fork or delete a session

Copy one session, transcript and all, when a setup is more than you need.