Save a machine with your repositories cloned and tools installed, so every new session starts ready in about a second.
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.
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.
In the Setups manager
Ask the agent
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”.
Once a session’s machine works the way you want, ask the agent to save it. It writes the setup script from the commands that actually worked here.Alpha will:
Collect the install, migrate and seed commands this session needed, in dependency order.
Save the setup under your account and build it on a fresh machine, not this one.
Tell you when it’s ready to pick on the home screen, or that it’s still building.
The agent can’t share a setup, and it replaces an existing setup of the same name only when you ask for exactly that.
Field
What it does
Limit
Name
Shown in the setup chip, the manager and session headers
60 characters, unique across your Alpha
Description
One line under the name in the manager
300 characters
Repositories
Cloned into /workspace/<name>, on the branch you give or the default
5, which count toward the 5 per session limit
Setup script
Runs once at build time, as root, with bash -e and no prompts. Your secrets and GITHUB_TOKEN are in its environment.
32 KB
Boot script
Runs on each fresh machine from the setup, before the agent starts. Edits apply without a rebuild.
32 KB; 5 minutes (default) per run
Notes for the agent
Handed to the agent with your messages in every session from the setup. They never appear in the transcript.
4,000 characters
Shared with
Accounts that can see the setup and start sessions from it
20 emails
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.
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.
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.
A setup’s repositories are frozen at the moment it was built. There are two ways to bring them forward.
Change
How
Who gets it
The latest code, or a quick install
Edit the Boot script. No rebuild needed.
Every machine created after the edit
New dependencies, repositories or setup script
Edit the setup, then Rebuild or Save & rebuild
Sessions started after the rebuild
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.”
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.
Owner
Someone it’s shared with
Anyone else, admins included
Sees it and starts sessions from it
Yes
Yes
No
Reads its build log
Yes
Yes
No
Edits, builds, cancels, deletes or shares it
Yes
No
No
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.
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.
Kept in the setup
Removed before it’s saved
Your repositories, dependencies and build outputs
Your secrets and GITHUB_TOKEN
A database the setup script started and seeded
Your git name and email
Every file the script wrote, keys included
The agent’s history and sign-ins from the build
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.
