Environment YAML

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

Node.js project

.ellipsis/environments/web-environment.yaml

ellipsis:
  kind: environment
  name: web-environment

repositories:
  - name: web-repo

image:
  setup: |
    cd /sandbox/web-repo
    npm ci

hooks:
  post_clone: |
    cd /sandbox/web-repo
    test -d node_modules

compute:
  memory: 8GB

Dependencies are cached. Each session checks that the dependency directory exists before the agent starts.

Python project

.ellipsis/environments/python-environment.yaml

ellipsis:
  kind: environment
  name: python-environment

repositories:
  - name: api-repo

image:
  setup: |
    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/environments/full-stack-environment.yaml

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

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

image:
  setup: |
    (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/environments/private-packages.yaml

ellipsis:
  kind: environment
  name: private-packages

repositories:
  - name: web-repo

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

image:
  setup: |
    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/environments/system-tools.yaml

ellipsis:
  kind: environment
  name: system-tools

repositories:
  - name: api-repo

image:
  dockerfile_append: |
    RUN apt-get update && apt-get install -y jq && rm -rf /var/lib/apt/lists/*
  setup: |
    cd /sandbox/api-repo
    npm ci

dockerfile_append accepts RUN instructions. Ellipsis supplies the base image, user, and entrypoint.

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:
  harness:
    type: 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 the environment's image setup. 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
`image.dockerfile_append`	Additional `RUN` instructions
`image.setup`	Shell script captured in the cached image
`hooks.post_start`	Shell script before repository preparation
`hooks.post_clone`	Shell script after checkout
`compute.cpu`	0.125 to 16 vCPUs; default 1
`compute.memory`	512MB 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

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:
  harness:
    type: claude_code
  environment:
    repositories:
      - name: api-repo
    image:
      setup: |
        cd /sandbox/api-repo
        npm ci
    compute:
      memory: 8GB