Environments
Set the repositories, setup scripts, and environment variables a session starts with.
An environment is the repositories, setup scripts, environment variables, and machine size a session starts with.
Define an environment
Commit this file to the repository's default branch:
Sessions using api-environment start with api-repo checked out, its npm dependencies installed, and the project built.
You can also create an environment on the dashboard's Environments page or with POST /v1/environments.
Use an environment
Select it in New session, pass it to the CLI with -e, or name it in an API request:
An agent names it in session.environment:
An unknown name fails the session at start. Without an environment, a session starts in a basic sandbox; there is no default environment.
Setup and hooks
| Hook | Runs | Use for |
|---|---|---|
hooks.build_base | The first time, and when a file in its inputs changes | Installing dependencies and system tools |
hooks.after_checkout | When a session needs a commit that isn't prepared yet | Building, generating code, starting services |
hooks.before_start | Every time a session starts or resumes | Quick per-session setup |
Scripts run in /sandbox as the sandbox user, under bash -eo pipefail: the first command that fails, including one inside a pipeline, stops the script and fails the session. The session's error names the hook and shows the end of its output. build_base and after_checkout each have 10 minutes; before_start has 5. Shell exports don't carry between scripts; put shared values under variables.
Reuse cached dependencies
Ellipsis saves the result of each setup script and reruns only what your change affects:
| You change | The next session runs |
|---|---|
| Nothing | before_start |
| A source file | after_checkout, then before_start |
A file in build_base.inputs | All 3 scripts |
The build_base script, a variable, or compute | All 3 scripts |
List every file your install reads in build_base.inputs, starting with the repository name. Include files such as .npmrc and workspace manifests: only the listed files exist while build_base runs. Globs, missing files, and symlinks fail the build. Omit inputs to rebuild on every commit, or set inputs: [] when the install reads no repository files.
Make after_checkout safe to run again on a workspace that already has its output. Saved results keep files and running services, so start services in the background (for example, docker compose up -d --wait) and wait until they're ready before the script exits. Keep secret values out of files your scripts write.
A resumed session keeps its workspace, including uncommitted changes. Setup changes apply to new sessions.
To rebuild from scratch, send "force_rebuild": true when starting a session. The session's environment log shows each script's output.
See the Environment schema reference for Python, multi-repository, variable, and MCP server examples.