Update environment
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization 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.
1Path Parameters
Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments.
Body
Writable fields for changing an environment. Omitted fields keep their stored value; server-owned identity, timestamps, setup verification, and warnings are never accepted as input.
Whether the environment boots the shared interactive browser display.
Provider-specific overflow settings. Omit to keep them; send {} to clear them.
Free-text note about what this environment provides. Send an empty string to clear it.
Plaintext environment variables. Omit to keep them; send {} to clear them.
Required when a Runs PATCH changes or bypasses a nonempty network policy, or enables privileged Docker. Copy network_policy and privileged from the last environment read; a stale snapshot is rejected.
Port inside the sandbox to expose over HTTP; 0 exposes nothing.
0 <= x <= 9007199254740991Seconds of inactivity before compute stops, from 120 through 7200 (2 hours); omit to keep the stored value or send 0 for the provider default. Computer use requires 0 or at least 600 seconds.
0 <= x <= 7200Caller-owned key/value data. Omit to keep it; send {} to clear it.
Files staged into the sandbox workspace. Omit to keep them; send [] to clear them.
Human-readable label shown wherever environments are listed.
Internet access for Runs environments. Omit to keep the current setting; send {} for unrestricted access. A nonempty policy limits destinations and cannot be combined with privileged Docker when changing access settings. Choose a compatible placement for limited access.
Whether the Runs sandbox may use privileged Docker. When changing access settings, privileged Docker requires unrestricted internet access (network_policy: {}). Omit to keep the current value, or send false to disable it.
Sandbox runtime that executes the session, chosen from the sandbox providers catalog.
Persistent workspace size in GiB, from 1 through 100; omit to keep the stored value or send 0 for the provider default.
0 <= x <= 100Caller-sized CPU and memory, accelerator, lifetime, and placement constraints. Send an empty object to return to provider sizing defaults.
Who may use the environment. Defaults to organization, meaning it is shared across the owning organization.
Deprecated. Must be empty or omitted; a non-empty map is rejected. Environment secret references are no longer supported: store secret values as vault credentials and attach them to the session with vault_ids or credential_refs. Send {} to clear references stored before the field was retired.
Setup script run after the sandbox is provisioned and before the agent starts. Send an empty script to clear it.
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.
0 <= x <= 9007199254740991Response
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.
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.
Server-assigned RFC 3339 timestamp of when the environment was created.
Server-assigned id of the environment; pass it when starting a session that should run in this sandbox.
Human-readable label shown wherever environments are listed.
Organization that owns the environment. Server-assigned from the caller's credentials.
Sandbox runtime that executes the session, chosen from the sandbox providers catalog.
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.
Who may use the environment. Defaults to organization, meaning it is shared across the owning organization.
Setup script run after the sandbox is provisioned and before the agent starts.
Server-assigned RFC 3339 timestamp of the most recent update to the environment.
Provider-specific overflow settings this schema does not model. Passed to the provider unchanged.
Free-text note about what this environment provides.
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.
Port inside the sandbox to expose over HTTP for services the agent starts; 0 exposes nothing.
0 <= x <= 9007199254740991Seconds 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.
0 <= x <= 9007199254740991Container image the sandbox boots. Set by the platform: new environments use the default runner image. Customize the sandbox itself with setup.script.
Caller-owned key/value data stored with the environment and returned unchanged.
Files or objects staged into the sandbox workspace when it is created. On update, omit to keep the current mounts; send [] to clear them.
Internet access for Runs environments. On update, omission keeps the current setting. Changing from another provider to Runs with an absent or {} saved policy requires an explicit network_policy: {"version":"v1","rules":[]} for No access or {} for unrestricted access. A nonempty policy limits destinations and cannot be combined with privileged Docker on create or when changing access settings. If the selected placement is incompatible, choose a compatible placement or send {} for unrestricted access. Send {} to clear a policy. Runs responses always include network_policy; {} means unrestricted.
Whether a Runs sandbox may use privileged Docker. Privileged Docker requires unrestricted internet access (network_policy: {}) 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 network_policy: {} or disable privileged Docker.
Size in GiB of the persistent workspace volume; 0 uses the provider default.
0 <= x <= 9007199254740991Deprecated 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.
RFC 3339 timestamp of the last setup script change. Server-assigned.
User who last changed the setup script. Server-assigned.
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 last_run.hint first when status is failed.
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.
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.
0 <= x <= 9007199254740991Reviewed template revision used to create this environment.