Environment schema reference

Complete environment examples and field reference.

Environment files live under .ellipsis/ on the default branch, with ellipsis.kind: environment and a unique name. See Environments for when each setup script runs.

Node.js project

1
ellipsis:
2
kind: environment
3
name: web-environment
4
5
repositories:
6
- name: web-repo
7
8
hooks:
9
build_base:
10
inputs:
11
- web-repo/package.json
12
- web-repo/package-lock.json
13
run: |
14
cd /sandbox/web-repo
15
npm ci
16
after_checkout: |
17
cd /sandbox/web-repo
18
npm run build --if-present
19
before_start: |
20
cd /sandbox/web-repo
21
test -d node_modules
22
23
compute:
24
memory: 8GB

npm ci reruns only when package.json or the lockfile changes. The build reruns for each new commit. before_start checks that dependencies exist each time a session starts or resumes.

Python project

1
ellipsis:
2
kind: environment
3
name: python-environment
4
5
repositories:
6
- name: api-repo
7
8
hooks:
9
build_base:
10
inputs: [api-repo/requirements.txt]
11
run: |
12
cd /sandbox/api-repo
13
python -m venv .venv
14
.venv/bin/pip install -r requirements.txt
15
16
variables:
17
- name: PYTHONUNBUFFERED
18
value: '1'
19
20
compute:
21
cpu: 2
22
memory: 8GB
23
timeout: 45m

The agent can run /sandbox/api-repo/.venv/bin/python with the project's dependencies.

Multiple repositories

1
ellipsis:
2
kind: environment
3
name: full-stack-environment
4
5
repositories:
6
- name: web-repo
7
ref: main
8
- name: api-repo
9
ref: main
10
11
hooks:
12
build_base:
13
inputs:
14
- web-repo/package.json
15
- web-repo/package-lock.json
16
- api-repo/requirements.txt
17
run: |
18
(cd /sandbox/web-repo && npm ci)
19
(cd /sandbox/api-repo && python -m venv .venv)
20
/sandbox/api-repo/.venv/bin/pip install -r /sandbox/api-repo/requirements.txt
21
22
compute:
23
cpu: 4
24
memory: 16GB

Each repository is checked out at /sandbox/<name>. A repository's owner defaults to your account.

Add environment variables and secrets

Set a plain value with value. For a secret, store it first, then list its name without a value:

1
ellipsis:
2
kind: environment
3
name: private-packages
4
5
repositories:
6
- name: web-repo
7
8
variables:
9
- name: NPM_TOKEN
10
- name: NODE_ENV
11
value: test
12
13
hooks:
14
build_base:
15
inputs: [web-repo/package.json, web-repo/package-lock.json, web-repo/.npmrc]
16
run: |
17
cd /sandbox/web-repo
18
npm ci

NODE_ENV is test, and NPM_TOKEN comes from the stored secret, so its value never appears in git. Both are available to setup scripts and the agent.

  • Names use letters, digits, and underscores, and can't start with a digit.
  • A missing secret fails the session.
  • Changing a variable reruns all setup scripts.
  • Names starting with ANTHROPIC_, OPENAI_, CODEX_, or CLAUDE_CODE_USE_, and CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_CONFIG_DIR, and ELLIPSIS_LLM_PROXY_URL, are rejected.

Install system tools

1
ellipsis:
2
kind: environment
3
name: system-tools
4
5
repositories:
6
- name: api-repo
7
8
hooks:
9
build_base:
10
inputs: [api-repo/package.json, api-repo/package-lock.json]
11
run: |
12
sudo apt-get update
13
sudo apt-get install -y jq
14
cd /sandbox/api-repo
15
npm ci

The agent can run jq. Install system packages in build_base with sudo.

Add an MCP server

List MCP servers under mcp_servers. Claude Code and Codex sessions both get their tools.

1
ellipsis:
2
kind: environment
3
name: api-with-tools
4
5
repositories:
6
- name: api-repo
7
8
mcp_servers:
9
- name: internal-tools
10
url: https://tools.example.com/mcp
11
headers:
12
Authorization: Bearer ${TOOLS_TOKEN}
13
- name: repo-tools
14
command: node
15
args: [/sandbox/api-repo/scripts/mcp-server.js]

Sessions using api-with-tools get the tools of both servers.

  • A server with url is a remote server that speaks streamable HTTP. Replace the example URL with your server's.
  • A server with command runs inside the sandbox, with optional args and env. Install anything it needs in build_base.
  • ${NAME} in headers or env reads the secret NAME when the session starts. It doesn't need a variables entry. A missing secret fails the session.
  • To add the tools of a connected Slack or Linear integration, list it by name: - slack or - linear. Listing an integration that isn't connected fails the session at start.
  • A repository's own .mcp.json is ignored.
  • With Codex, a server that fails to start fails the turn.

Inline environments

An agent can define its environment in session.environment instead of naming a saved one. Use the same fields without the ellipsis block:

1
session:
2
claude_code:
3
model: claude-opus-5-5
4
environment:
5
repositories:
6
- name: api-repo
7
hooks:
8
build_base:
9
inputs: [api-repo/package.json, api-repo/package-lock.json]
10
run: |
11
cd /sandbox/api-repo
12
npm ci
13
compute:
14
memory: 8GB

Fields

Identifies the file.

Each repository is checked out at /sandbox/<name>.

Environment variables for setup scripts and the agent. Changing a variable reruns all setup scripts.

Setup scripts; see Setup and hooks.

The size of the environment.

slack, linear, remote servers, or local servers; see Add an MCP server.

Memory accepts MB or GB. Timeout accepts s, m, and h, including combinations such as 1h30m, within the allowed range.

On this page

Node.js projectPython projectMultiple repositoriesAdd environment variables and secretsInstall system toolsAdd an MCP serverInline environmentsFields
Schedule a demo