Environment schema reference

For an introduction and setup instructions, see Environments.

Environment files live under .ellipsis/ on the default branch. Set ellipsis.kind: environment and give the environment a unique name.

Node.js project

ellipsis:
  kind: environment
  name: web-environment

repositories:
  - name: web-repo

hooks:
  build_base:
    inputs:
      - web-repo/package.json
      - web-repo/package-lock.json
    run: |
      cd /sandbox/web-repo
      npm ci
  after_checkout: |
    cd /sandbox/web-repo
    npm run build --if-present
  before_start: |
    cd /sandbox/web-repo
    test -d node_modules

compute:
  memory: 8GB

Dependencies are cached independently of TypeScript source. Compilation is cached for the requested source revision. Each session checks that the dependency directory exists before the agent starts or resumes.

Python project

ellipsis:
  kind: environment
  name: python-environment

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs: [api-repo/requirements.txt]
    run: |
      cd /sandbox/api-repo
      python -m venv .venv
      .venv/bin/pip install -r requirements.txt

variables:
  - name: PYTHONUNBUFFERED
    value: '1'

compute:
  cpu: 2
  memory: 8GB
  timeout: 45m

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

Multiple repositories

ellipsis:
  kind: environment
  name: full-stack-environment

repositories:
  - name: web-repo
    ref: main
  - name: api-repo
    ref: main

hooks:
  build_base:
    inputs:
      - web-repo/package.json
      - web-repo/package-lock.json
      - api-repo/requirements.txt
    run: |
      (cd /sandbox/web-repo && npm ci)
      (cd /sandbox/api-repo && python -m venv .venv)
      /sandbox/api-repo/.venv/bin/pip install -r /sandbox/api-repo/requirements.txt

compute:
  cpu: 4
  memory: 16GB

Both repositories are available under /sandbox/. A repository's owner defaults to the account; set it explicitly when needed.

Stored secrets

Store NPM_TOKEN through Environments > Secrets or PUT /v1/secrets. Reference its name without putting the value in git.

ellipsis:
  kind: environment
  name: private-packages

repositories:
  - name: web-repo

variables:
  - name: NPM_TOKEN
  - name: NODE_ENV
    value: test

hooks:
  build_base:
    inputs: [web-repo/package.json, web-repo/package-lock.json, web-repo/.npmrc]
    run: |
      cd /sandbox/web-repo
      npm ci

This assumes the repository's npm configuration reads NPM_TOKEN from the environment. The secret is available to setup and the session. Do not write its value into a cached file.

A missing stored secret fails the session. Stored values cannot be read back through the dashboard or API.

System tools

ellipsis:
  kind: environment
  name: system-tools

repositories:
  - name: api-repo

hooks:
  build_base:
    inputs: [api-repo/package.json, api-repo/package-lock.json]
    run: |
      sudo apt-get update
      sudo apt-get install -y jq
      cd /sandbox/api-repo
      npm ci

Install system tools in build_base using sudo. Ellipsis supplies the managed toolchain.

MCP tools for Codex

Codex sessions can use connected Slack and Linear integrations, custom stdio servers, and remote streamable HTTP servers. Built-in integrations follow their inclusion settings; listing a name opts into an integration configured for explicit inclusion.

session:
  codex:
    model: gpt-5.6-terra
  environment:
    mcp_servers:
      - linear
      - name: internal-tools
        url: https://tools.example.com/mcp
        headers:
          Authorization: Bearer ${TOOLS_TOKEN}

The session receives Linear tools when the integration is connected and tools from your HTTP server. Replace the example URL with your server and store TOOLS_TOKEN in your account's secrets. ${NAME} references resolve at session start; a missing secret fails the session.

For a server that runs inside the sandbox, replace url and headers with command, optional args, and optional env. Install its executable through build_base. An MCP server that cannot initialize fails the Codex turn.

Fields

Field	Values and behavior
`ellipsis.kind`	Required `environment`
`ellipsis.name`	Unique environment name
`repositories`	List of `name`, optional `owner`, and optional `ref`
`variables`	List of `name` and optional plaintext `value`; omit `value` to use a stored secret
`hooks.build_base`	Script or `{run, inputs}`; builds the reusable dependency base
`hooks.build_base.inputs`	Exact repository-qualified files; omit for all source, or use `[]` for no source
`hooks.after_checkout`	Script or `{run}`; prepares the requested revision before saving its sandbox
`hooks.before_start`	Script or `{run}`; runs before a session starts or resumes
`compute.cpu`	2 to 32 vCPUs; default 2
`compute.memory`	4096MB to 64GB; default 4096MB
`compute.timeout`	60 seconds to 1 hour; default 1 hour
`mcp_servers`	Built-in names or custom stdio/HTTP servers for Codex

See Setup and hooks for cache behavior, script limits, and migrating legacy hooks.

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

Inline environments

Use the same fields directly in an automation's session.environment. Omit the environment's ellipsis block:

session:
  claude_code: {}
  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
    compute:
      memory: 8GB

Environment schema reference

On this page