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.
Add an MCP server for one session
Ellipsis never merges environments. A session's environment is a saved environment's name, used as written, or a complete environment. On POST /v1/agents/{id}/sessions, either one replaces the agent's environment.
To add an MCP server to a saved environment for one session, fetch the environment first:
Copy the response's environment object without its ellipsis block, add the server to mcp_servers, and send the result as environment in POST /v1/sessions or POST /v1/agents/{id}/sessions:
The session starts with everything in api-environment plus the tools of the docs server. MCP servers don't affect setup, so the session reuses the saved setup of api-environment without rerunning its scripts. The session's environment.id is null because it runs a different environment from api-environment. Sending the ellipsis block fails with a 422.
An agent that always needs the extra server names an environment file that lists it, as in Add an MCP server.
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 every hook, including validate, 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 |
hooks.validate | Every time a session starts or resumes, after before_start | Checking that the tools the agent needs work, for example command -v jq |
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 and validate each have 5 minutes. Shell exports don't carry between scripts, so 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 |
validate runs last every time and is never cached.
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 and wait until they're ready before the script exits. An environment has no Docker, so install it in build_base before a script runs docker compose up -d --wait. 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.