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
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
The agent can run /sandbox/api-repo/.venv/bin/python with the project's dependencies.
Multiple repositories
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:
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_,GEMINI_,GOOGLE_, orCLAUDE_CODE_USE_, andCLAUDE_CODE_OAUTH_TOKEN,CLAUDE_CONFIG_DIR, andELLIPSIS_LLM_PROXY_URL, are rejected.
Install system tools
The agent can run jq. Install system packages in build_base with sudo. validate fails the session before the agent starts if a tool is missing, and fails the pull request's environment check before the change merges.
Add an MCP server
List MCP servers under mcp_servers. Claude Code and Codex sessions both get their tools.
Sessions using api-with-tools get the tools of both servers.
- A server with
urlis a remote server that speaks streamable HTTP. Replace the example URL with your server's. - A server with
commandruns inside the sandbox, with optionalargsandenv. Install anything it needs inbuild_base. ${NAME}inheadersorenvreads the secretNAMEwhen the session starts. It doesn't need avariablesentry. A missing secret fails the session.- To add the tools of a connected Slack or Linear integration, list it by name:
- slackor- linear. Listing an integration that isn't connected fails the session at start. - A repository's own
.mcp.jsonis ignored. - With Codex, a server that fails to start fails the message.
Label an environment
Tag an environment for your own use with labels and annotations under ellipsis.metadata. An agent takes the same block, and so does a session's metadata.
GET /v1/environments/{id} returns the labels and annotations in environment.ellipsis.metadata. Metadata doesn't change how sessions run, so editing it reruns no setup scripts.
GET /v1/environments?label=python lists only environments with that label, and annotation=owner:priya-shah only those with that annotation. Repeat either to require every one. GET /v1/agents and GET /v1/sessions take the same filters.
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:
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 and idle accept s, m, and h, including combinations such as 1h30m, within the allowed range. timeout caps one message's work, 1 minute to 22 hours, default 4 hours, and a message that reaches it ends stopped with reason timeout. idle is how long the environment stays awake after the agent finishes with no message waiting, 10 seconds to 1 hour, default 10 minutes. Then it pauses, and the next message resumes it with its files and processes. A session started with interactive: false ends when its message ends and never pauses.