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.

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 server definitions; currently unavailable for session starts

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