Skip to main content
GET
Get environment

Authorizations

Authorization
string
header
required

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

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

environmentId
string<uuid>
required

Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments.

Response

A standalone sandbox environment a session executes in.

A standalone sandbox environment a session executes in.

computerUse
boolean
required

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

createdAt
string<date-time>
required
read-only

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

environmentId
string
required
read-only

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.

organizationId
string
required
read-only

Organization that owns the environment. Server-assigned from the caller's credentials.

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.

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.

updatedAt
string<date-time>
required
read-only

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.

envVars
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; store them as vault credentials instead. On update, omit to keep the current variables; send {} to clear them.

httpPort
integer<int64>

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

Required range: 0 <= x <= 9007199254740991
idleStopAfterSeconds
integer<int64>

Seconds of inactivity after which a running sandbox is stopped, from 120 to 2592000 (30 days); 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.

Required range: 0 <= x <= 9007199254740991
image
string
read-only

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.

networkPolicy
object

Internet access for Runs environments. An empty object means unrestricted access.

privileged
boolean

Whether a Runs sandbox may use privileged Docker. Privileged Docker requires unrestricted internet access (networkPolicy: {}) on create or when changing access settings. Omit on update to keep the current value, or send false to disable it. New Runs environments and transitions from another provider default to false. Existing environments with both limited internet access and privileged Docker remain visible and allow edits to other settings. To start a new session, set networkPolicy: {} or disable privileged Docker.

pvcSizeGi
integer<int64>

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

Required range: 0 <= x <= 9007199254740991
secrets
object

Deprecated and always empty for new environments. Environment secret references are no longer supported; use vault credentials instead. An environment stored with references cannot start sessions or setup runs until an update sends {} to clear them; clearing them marks the setup verdict stale, so re-test afterwards.

setupUpdatedAt
string<date-time>
read-only

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

setupUpdatedByUserId
string
read-only

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

setupVerification
object
read-only

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

setupWarnings
object[]
read-only

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.

stoppedDeleteAfterSeconds
integer<int64>

Seconds after a sandbox stops before it may be released, from 3600 (an hour) to 2592000 (30 days); 0 uses the service default. This does not expire the session. Send another message to resume it; /workspace files can be used when its workspace reopens.

Required range: 0 <= x <= 9007199254740991
template
object

Reviewed template revision used to create this environment.