Environments

An environment config defines a VM's repositories, installed dependencies, environment variables, hooks, and compute.

The Environments page has four tabs:

• Env configs lists the definitions you select when starting sessions.
• VMs lists each machine once, including machines reused across session resumes. Open a VM to see its last recorded state, resources, repositories, and session.
• VM images lists reusable snapshots of prepared environments, including their repository revisions and expiration dates. Images save build work when a new VM starts.
• Secrets manages the variables available to your environments.

Use GET /v1/vms and GET /v1/vms/{vm_id} to inspect machines, or GET /v1/vm-images and GET /v1/vm-images/{image_id} to inspect image metadata. Both lists accept limit and offset and return next_offset when another page exists.

Define an environment

Commit this file on the repository's default branch:

ellipsis:
  kind: environment
  name: api-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
  after_checkout: |
    cd /sandbox/api-repo
    npm run build --if-present

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

Sessions using api-environment start with api-repo checked out and its npm dependencies installed.

You can also create an environment in the dashboard or with POST /v1/environments. The API accepts the same definition as JSON under environment.

Use an environment

Select it in New session, or name it in a session request:

{
  "harness": { "type": "claude_code" },
  "environment": "api-environment",
  "prompt": "Run the tests and fix one failure."
}

An automation references it in session.environment:

session:
  harness:
    type: claude_code
  environment: api-environment

A missing environment name fails at start. Omitting an environment uses the basic sandbox; there is no account default environment.

Setup and hooks

Scripts run as the sandbox user in /sandbox. Each script can be a string or an object with run. A nonzero exit fails the session. Each build script has a 10-minute limit; before_start has a 5-minute limit.

Reuse cached dependencies

build_base.inputs lists exact files relative to /sandbox, including the repository name. Only those files are available during the base build. Their contents and file modes determine reuse, together with the script, toolchain, compute, and build configuration. Include every file the install reads, such as .npmrc, workspace package manifests, and installation scripts. Missing files and symlinks fail the build. Glob patterns are not supported.

Omitting inputs makes all source available and rebuilds the base when any source revision changes. An explicit inputs: [] builds without repository files.

With the Node example above:

• Editing a TypeScript file reuses the dependency base, checks out the new revision, and runs after_checkout.
• Changing the lockfile builds a new dependency base, then runs after_checkout.
• Starting another session on a prepared revision skips both build scripts. Only before_start, if configured, runs again.

before_start runs when a session starts or resumes, not on every message or every Git checkout the agent performs. Its work adds to startup latency. Shell exports do not carry between scripts; declare shared values under variables.

A resumed session keeps its existing workspace, including uncommitted changes. Changes to build configuration apply when a new sandbox is prepared, or when you explicitly rebuild the session's sandbox.

To test a clean build, send "force_rebuild": true when starting a session. Inspect the environment log in the session.

Build snapshots retain files and running services. Start services in the background with their output redirected to files, or use docker compose up -d --wait, and verify readiness before the build script exits. Build output is private to your account; keep secrets out of generated files and logs.

Use hooks.build_base for system tools and dependencies, hooks.after_checkout for source preparation, and hooks.before_start for session initialization. The image block is no longer accepted in new YAML or API requests. Existing stored environments are converted to hooks when read; update repository-managed YAML before syncing it again.

See Environment YAML for multi-repository, secret, toolchain, and compute examples.