Create environment
Defines the sandbox an agent session runs in and returns the stored environment, including its generated environment_id. The provider must be one this deployment reports from managedAgentsListSandboxProviders. Nothing is provisioned by this configuration write; compute is allocated when managedAgentsCreateEnvironmentSetupRun or a session references the environment. An environment with a setup script must be verified (managedAgentsCreateEnvironmentSetupRun) before a session on the runs or docker provider will start. Send Idempotency-Key to make a retry after an ambiguous transport failure replay the original response instead of creating another 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.
1Body
Request body for creating an environment: the sandbox image, setup, compute sizing, networking, and lifecycle a session's sandbox is provisioned from. Server-managed fields are not accepted.
Human-readable label for the environment. Required, and not blank; surrounding whitespace is trimmed.
256Environment runtime: runs (managed agent runner) or docker (local development). Any other value is rejected, including the retired self_hosted and rma names.
Enable the shared interactive browser display. The server sets http_port to 6901; false disables it.
Provider-specific overflow config.
Optional free-text note about what this environment is for.
Environment variables injected into the sandbox. Each name must be letters, digits and underscores, not starting with a digit.
TCP port inside the sandbox that the provider exposes for HTTP traffic. Omit or send 0 if the workload serves nothing.
0 <= x <= 65535Seconds of inactivity after which the sandbox is stopped, from 60 to 2592000 (30 days). Omit or send 0 to use the provider's lifecycle policy instead of a per-environment one. Computer use requires 0 or at least 600 seconds.
0 <= x <= 9007199254740991Free-form caller-owned JSON stored with the environment and returned on reads. Not interpreted by the service.
Files staged into the sandbox workspace on create.
Runs egress policy. Omit to derive deny-all. A nonempty policy requires GKE: the runtime selects GKE when placement is omitted, or accepts explicit GKE placement. With explicit non-GKE placement, send {} for unrestricted egress or change placement to GKE.
Whether the Runs sandbox may use privileged Docker. Defaults to false independently of network_policy. Compute creation fails closed unless Agent Service can enforce the requested combination.
Size in gibibytes of the persistent volume attached to the sandbox workspace, from 1 to 1000. Omit or send 0 to let the sandbox provider choose.
0 <= x <= 1000Compute sizing: cpu_milli and memory_mib for a CPU environment, or one exclusive accelerator for a GPU environment with service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory.
Visibility of the environment record within the organization. organization is the only value; it is also the default when omitted.
Env-var name -> secret-manager reference (never plaintext).
Setup script run once on fresh compute after the sandbox is provisioned, before the agent starts. Verify it with managedAgentsCreateEnvironmentSetupRun before starting sessions.
Seconds a stopped sandbox is retained before deletion, after which its workspace is gone. Omit or send 0 to use the provider's lifecycle policy.
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; use secrets 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; 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. 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.
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.
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.
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. The first edit to a legacy Runs environment persists its existing effective setting explicitly. Compute creation fails closed unless Agent Service can enforce the requested combination.
Size in GiB of the persistent workspace volume; 0 uses the provider default.
0 <= x <= 9007199254740991Environment 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.
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 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 a stopped sandbox is retained before deletion; 0 uses the provider default.
0 <= x <= 9007199254740991