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:

```yaml title=".ellipsis/environments/api-environment.yaml"
ellipsis:
  kind: environment
  name: api-environment

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs:
      - api-repo/package.json
      - api-repo/package-lock.json
    run: |
      cd /sandbox/api-repo
      npm ci
  after_checkout: |
    cd /sandbox/api-repo
    npm run build --if-present

compute:
  cpu: 2
  memory: 8GB
  timeout: 30m
```

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:

```bash
ellipsis --model claude-opus-5-5 -e api-environment "Run the tests and fix one failure."
```

```json
{
  "environment": "api-environment",
  "claude_code": {
    "model": "claude-opus-5-5",
    "prompt": "Run the tests and fix one failure."
  }
}
```

An agent names it in `session.environment`:

```yaml fragment
session:
  claude_code:
    model: claude-opus-5-5
  environment: api-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](/docs/environments/schema) for Python, multi-repository, variable, and MCP server examples.