Images and builds
How the cloud environment's image is built, how to read the Builds tab, and how to roll back to an earlier image.
An image is the prepared starting point for new cloud sessions. It contains the repositories and completed install steps from your team's cloud setup.
A build starts from Alan's base image in a clean builder, copies in each repository at the head of its configured branch, and runs that repository's install steps (its .alan/environment.json, or its saved Install script). It is not a copy of any running session. Uncommitted work, files you created by hand in a session, and session-only variables never reach it.
What starts a build
The Type column of the Builds tab shows what started each build:
| Type | Started by |
|---|---|
| Manual | More actions → Trigger build on the Cloud Environment page |
| Agent | An agent, for example during setup with an agent |
| Preview | An agent testing a branch. Preview builds never become the current image. |
| Base update | Alan updating its base image |
Saving scripts or changing repositories doesn't start a build, and neither do pushes or merges. Trigger a build when you want new sessions to get the change.
Read the Builds tab
Open the team's Settings → Cloud Environment → Builds. Builds are listed newest first, ten per page.
| Column | Shows |
|---|---|
| Build | A short build ID; Current marks the build whose image new sessions use |
| Type | Manual, Agent, Preview, or Base update |
| Status | Queued, Building, Succeeded, Failed, Cancelled, or Superseded |
| Commit | The first repository and commit built, for example api@4f9c2a1 +1 |
| Started, Duration | When it started and how long it took |
Select a build ID to expand it: Type, Started, Duration, each repository at the commit it was built from, and View build logs when logs are available. A failed build shows Failed at with the step name and its output.
If the environment has never been built, the tab reads No builds yet — "A build clones your repositories and runs the install script, so new sessions start ready."
Roll back with Use this image
To roll back, hover over an earlier successful build and choose Use this image. The action is available only while its image is still usable; preview builds and retired images cannot be selected. Alan confirms with New sessions now start from this image, or New sessions will start from this image once it is ready while the image is being prepared.
Switching images only affects new sessions. It doesn't move an open session, a running computer, or its files.
When a build fails
A failed build leaves the current image in place, so sessions keep working on the previous one. The environment's status badge shows Build failed.
- Expand the failed build and read Failed at and the output.
- Fix the cause shown in the log. Check for missing dependencies, secrets, repository access, or commands that rely on files created by hand in a previous session. Run Docker services in the start script; Docker is not available during the image build.
- Choose Trigger build again, or ask the setup session to fix the scripts and rebuild.
Before you build
- The repositories and branches in Setup are the ones new sessions should start with.
- Code, dependency files, and setup scripts are committed and pushed to those branches. Keep secrets in the environment's variables or files.
- Install steps run in a clean shell without your session's state.
- Secrets live in Setup → Environment Variables, not in scripts.