Skip to main content
GET
Get environment

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Path Parameters

environment_id
string<uuid>
required

Environment id (UUID) as returned by createEnvironment or listEnvironments.

Response

A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session.

A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session.

computer_use
boolean
required

Whether this environment boots the shared interactive Chromium display used by the computer and human-handoff tools. The server projects this to http_port 6901.

created_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of when the environment was created.

environment_id
string
required

Server-assigned id of the environment; pass it when starting a session that should run in this sandbox.

name
string
required

Human-readable label shown wherever environments are listed.

organization_id
string
required

Organization that owns the environment. Server-assigned from the caller's credentials; a value sent in a request body is ignored.

provider
string
required

Sandbox runtime that executes the session, chosen from the sandbox providers catalog.

resources
object
required

Caller-sized CPU and memory for CPU environments, or one exclusive accelerator with service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory for GPU environments, plus lifetime and placement constraints.

Example:
scope
string
required

Who may use the environment. Defaults to organization, meaning it is shared across the owning organization.

setup
object
required

Setup script run after the sandbox is provisioned and before the agent starts.

Example:
updated_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of the most recent update to the environment.

config
object

Provider-specific overflow settings this schema does not model. Passed to the provider unchanged.

description
string

Free-text note about what this environment provides.

env_vars
object

Plaintext environment variables exported in the sandbox. They become the whole container environment, including the runner entrypoint's, so PATH is refused (env_vars.PATH): managed images select /workspace/.venv themselves. A Runs session using one-time setup after its runner changes also refuses startup-hook names such as BASH_ENV, HOME, PYTHONPATH, and LD_PRELOAD; re-test to capture a compatible image instead. Never put secrets here; use secrets instead. On update, omit to keep the current variables; send {} to clear them.

http_port
integer<int64>

Port inside the sandbox to expose over HTTP for services the agent starts; 0 exposes nothing.

idle_stop_after_seconds
integer<int64>

Seconds of inactivity after which a running sandbox is stopped; 0 uses the provider default. A computer-enabled environment requires 0 or at least 600 seconds so its five-minute handoff heartbeat arrives before idle-stop.

image
string

Container image the sandbox boots. Omit to use the provider's default image. For the Agent runner provider only the deployment's own runner repository or a sibling published beside it (for example rma-runner-recursion) is accepted, and it must be omitted when an accelerator is requested, which always boots the platform's GPU runner. Customize the sandbox itself with setup.script.

metadata
object

Caller-owned key/value data stored with the environment and returned unchanged.

mounts
object[]

Files or objects staged into the sandbox workspace when it is created. On update, omit to keep the current mounts; send [] to clear them.

network_policy
object

Runs egress rules. On update, omission keeps the stored policy. Changing from a non-Runs provider to Runs with an absent or {} stored policy requires an explicit network_policy: {"version":"v1","rules":[]} for deny-all or {} for unrestricted egress. A nonempty policy requires GKE; with explicit non-GKE placement, send {} for unrestricted egress or change placement to GKE. Send {} to clear a policy. Runs responses always include network_policy; {} means unrestricted.

privileged
boolean

Whether a Runs sandbox may use privileged Docker. Independent of network_policy; omit on update to retain the saved value, or send false to disable it. New Runs environments and transitions from another provider default to false. Existing Runs environments retain their earlier effective setting until edited. Compute creation fails closed unless Agent Service can enforce the requested combination.

pvc_size_gi
integer<int64>

Size in GiB of the persistent workspace volume; 0 uses the provider default.

secrets
object

Environment variable name to secret-manager reference. References only, never plaintext values; the runtime resolves them at start. The one-time Runs setup fallback applies the same startup-hook name restriction to secrets and vault-injected variables. On update, omit to keep the current references; send {} to clear them.

setup_updated_at
string<date-time>

RFC 3339 timestamp of the last setup script change. Server-assigned.

setup_updated_by_user_id
string

User who last changed the setup script. Server-assigned.

setup_verification
object

Server-owned verdict on the setup script: whether a manual setup run has proven this exact configuration on real compute. Read status and stale before starting sessions; read last_run.hint first when status is failed. Ignored in request bodies.

Example:
setup_warnings
object[]

Advisory findings about the setup script (bash -lc wrapping, curl | sh, unpinned installs, ambiguous system Python, PATH replacement, or non-persistent shell activation), plus legacy_setup_discarded when the stored setup predates setup.script and is not run. Never block a save; computed on read.

stopped_delete_after_seconds
integer<int64>

Seconds a stopped sandbox is retained before it is deleted along with its volume; 0 uses the provider default.