Sandbox

Every Ellipsis agent runs in an isolated cloud sandbox with your repositories already cloned. The sandbox is ephemeral: it is created when a run starts and torn down when the run finishes, so nothing persists between runs.

Detecting the sandbox

Ellipsis sets the ELLIPSIS_SANDBOX_ID environment variable in every sandbox, and nowhere else. If your agents need to determine whether they're running on the Ellipsis cloud or somewhere else, have them check ELLIPSIS_SANDBOX_ID.

Giving an agent environment variables

An agent reads sandbox variables as ordinary environment variables. Anything you name under an agent's sandbox.variables is set in that run's environment, so a prompt step, a setup script, or a tool the agent shells out to can read it the usual way ($NPM_TOKEN, process.env.API_BASE_URL, os.environ["LINEAR_API_KEY"]). There is no Ellipsis-specific way to read them.

Each variables entry is one name. Give it an inline value to hardcode non-secret config directly in the file, or omit the value to resolve it by name from your account's sandbox-variables store at run time, so secrets never live in the config:

sandbox:
  variables:
    - name: LINEAR_API_KEY      # resolved from your sandbox-variables store
    - name: LOG_LEVEL
      value: info               # hardcoded inline

Only the variables an agent names reach that agent's sandbox; the rest of your stored variables never appear. If an agent names a variable that has no inline value and no stored value, the run fails immediately rather than starting with the variable unset, so define it first. See the agent config reference for the full sandbox field.

Storing values for an agent to use

Stored variables live once on your account and are write-only: you upload a value, but neither the API nor the dashboard ever returns it again, only its name and timestamps. Manage them from the dashboard, or programmatically with the REST API:

• PUT /v1/sandboxes/variables creates or updates variables by name in a single batch.
• GET /v1/sandboxes/variables lists the stored names.
• DELETE /v1/sandboxes/variables/{name} removes one.

An account can hold up to 500 variables. See the REST API reference for request and response shapes.