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.
Check a change on a pull request
A pull request that changes an environment file gets an Ellipsis environment check. Ellipsis clones the environment's repositories, with the pull request's repository at the pull request's commit, runs all three hooks, and reports the result on the pull request. A failing check names the hook and shows the end of its output. Pull requests from forks are not checked.
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.