> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Update environment > Applies a partial update and returns the stored environment; omitted fields keep their current values. 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 provider is validated only when the request actually names one. Sending setup with an empty script clears the script; omitting setup leaves it. Any change to provider, image, setup (script or timeout), resources, workspace disk size, provider config, variables, secret references, mounts, network policy, or effective Docker privilege marks the previous setup verification stale; name, description, metadata, and http_port do not. Call createEnvironmentSetupRun separately after the update to re-run setup. Sessions already running keep the spec they started with, so a change takes effect on the next session start. A Runs update that changes or bypasses a nonempty network_policy, or enables privileged Docker, requires expected_access with the network_policy and privileged values from the last environment read. A missing access snapshot returns 428; a stale one returns 412. A concurrent configuration edit may return 409; reload and retry. Send Idempotency-Key to make a retry after an ambiguous transport failure replay the original response. ## OpenAPI ````yaml /managed-agents/openapi.yaml patch /managed-agents/v1/environments/{environment_id} openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/environments/{environment_id}: patch: tags: - Environments summary: Update environment description: >- Applies a partial update and returns the stored environment; omitted fields keep their current values. 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 provider is validated only when the request actually names one. Sending setup with an empty script clears the script; omitting setup leaves it. Any change to provider, image, setup (script or timeout), resources, workspace disk size, provider config, variables, secret references, mounts, network policy, or effective Docker privilege marks the previous setup verification stale; name, description, metadata, and http_port do not. Call createEnvironmentSetupRun separately after the update to re-run setup. Sessions already running keep the spec they started with, so a change takes effect on the next session start. A Runs update that changes or bypasses a nonempty network_policy, or enables privileged Docker, requires expected_access with the network_policy and privileged values from the last environment read. A missing access snapshot returns 428; a stale one returns 412. A concurrent configuration edit may return 409; reload and retry. Send Idempotency-Key to make a retry after an ambiguous transport failure replay the original response. operationId: managedAgentsUpdateEnvironment parameters: - description: >- Environment id (UUID) as returned by createEnvironment or listEnvironments. in: path name: environment_id required: true schema: description: >- Environment id (UUID) as returned by createEnvironment or listEnvironments. format: uuid type: string - description: >- 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. in: header name: Idempotency-Key schema: description: >- 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. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsUpdateEnvironmentRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsEnvironment' description: >- A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' '409': headers: Retry-After: description: >- When present, delay in seconds or an HTTP-date after which the caller may retry; absence supplies no retry advice. schema: type: string style: simple description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress - $ref: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' discriminator: propertyName: code mapping: idempotency_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress revision_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorRevisionConflict '412': description: A request precondition does not match the current resource state. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPreconditionFailed' '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '422': description: The request is well formed but failed semantic validation. content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsApiErrorSandboxProviderDisabled '428': description: The request requires a precondition. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPreconditionRequired' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' '500': description: An unexpected server-side failure. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' - $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation discriminator: propertyName: code mapping: internal_error: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' invariant_violation: $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': description: >- A dependency is unavailable. Consult details.retryable and Retry-After when present before retrying. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: idempotency_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable '504': description: The service did not respond before the timeout. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsUpdateEnvironmentRequest: additionalProperties: false description: >- Writable fields for a partial environment update. Omitted fields keep their stored values; null is not accepted. minProperties: 1 properties: computer_use: description: >- Whether the environment boots the shared interactive browser display. type: boolean x-lint-ignore: - camel-case-properties config: additionalProperties: {} description: >- Provider-specific overflow settings. Omit to keep them; send {} to clear them. type: object description: description: >- Free-text note about what this environment provides. Send an empty string to clear it. type: string env_vars: additionalProperties: type: string description: >- Plaintext environment variables. Omit to keep them; send {} to clear them. type: object x-lint-ignore: - camel-case-properties expected_access: $ref: '#/components/schemas/ManagedAgentsEnvironmentAccessExpectation' description: >- 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. x-lint-ignore: - camel-case-properties http_port: description: Port inside the sandbox to expose over HTTP; 0 exposes nothing. format: int64 minimum: 0 type: integer x-lint-ignore: - camel-case-properties idle_stop_after_seconds: description: >- Seconds of inactivity after which a running sandbox is stopped; 0 uses the provider default. format: int64 minimum: 0 type: integer x-lint-ignore: - camel-case-properties image: description: >- Container image the sandbox boots. Send an empty string to return to the provider default. type: string metadata: additionalProperties: {} description: Caller-owned key/value data. Omit to keep it; send {} to clear it. type: object mounts: description: >- Files staged into the sandbox workspace. Omit to keep them; send [] to clear them. items: $ref: '#/components/schemas/ManagedAgentsEnvironmentMount' type: array name: description: Human-readable label shown wherever environments are listed. type: string network_policy: additionalProperties: {} description: >- Runs egress rules. Omit to keep them; send {} for unrestricted egress. A nonempty policy requires GKE placement. type: object x-lint-ignore: - camel-case-properties privileged: description: >- Whether the Runs sandbox may use privileged Docker. Omit to retain the saved value, or send false to disable it. type: boolean provider: description: >- Sandbox runtime that executes the session, chosen from the sandbox providers catalog. type: string pvc_size_gi: description: >- Size in GiB of the persistent workspace volume; 0 uses the provider default. format: int64 minimum: 0 type: integer x-lint-ignore: - camel-case-properties resources: $ref: '#/components/schemas/ManagedAgentsEnvironmentResources' description: >- Caller-sized CPU and memory, accelerator, lifetime, and placement constraints. Send an empty object to return to provider sizing defaults. scope: description: >- Who may use the environment. Defaults to organization, meaning it is shared across the owning organization. type: string secrets: additionalProperties: type: string description: >- Environment variable name to secret-manager reference. Omit to keep them; send {} to clear them. type: object setup: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetup' description: >- Setup script run after the sandbox is provisioned and before the agent starts. Send an empty script to clear it. stopped_delete_after_seconds: description: >- Seconds a stopped sandbox is retained before deletion; 0 uses the provider default. format: int64 minimum: 0 type: integer x-lint-ignore: - camel-case-properties type: object example: computer_use: true config: key: example description: example env_vars: key: example expected_access: network_policy: key: example privileged: true http_port: 1 idle_stop_after_seconds: 1 image: example metadata: key: example mounts: - mount_path: example source: example name: example-name network_policy: key: example privileged: true provider: example pvc_size_gi: 1 resources: accelerator: count: 1 name: example-name type: example cpu_milli: 1 memory_mib: 1 placement: allow_spot: true max_price_per_hour_usd: 1.5 min_accelerator_vram_gb: 1 providers: - example regions: - example timeout_seconds: 1 scope: example secrets: key: example setup: script: example timeout_seconds: 1 stopped_delete_after_seconds: 1 ManagedAgentsEnvironment: description: >- A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session. properties: computer_use: description: >- 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. type: boolean config: additionalProperties: {} description: >- Provider-specific overflow settings this schema does not model. Passed to the provider unchanged. type: object created_at: description: >- Server-assigned RFC 3339 timestamp of when the environment was created. format: date-time readOnly: true type: string description: description: Free-text note about what this environment provides. type: string env_vars: additionalProperties: type: string description: >- 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. type: object environment_id: description: >- Server-assigned id of the environment; pass it when starting a session that should run in this sandbox. readOnly: true type: string http_port: description: >- Port inside the sandbox to expose over HTTP for services the agent starts; 0 exposes nothing. format: int64 minimum: 0 type: integer idle_stop_after_seconds: description: >- 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. format: int64 minimum: 0 type: integer image: description: >- 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. type: string metadata: additionalProperties: {} description: >- Caller-owned key/value data stored with the environment and returned unchanged. type: object mounts: description: >- Files or objects staged into the sandbox workspace when it is created. On update, omit to keep the current mounts; send [] to clear them. items: $ref: '#/components/schemas/ManagedAgentsEnvironmentMount' type: array name: description: Human-readable label shown wherever environments are listed. type: string network_policy: additionalProperties: {} description: >- 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. type: object organization_id: description: >- Organization that owns the environment. Server-assigned from the caller's credentials. readOnly: true type: string privileged: description: >- 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. type: boolean provider: description: >- Sandbox runtime that executes the session, chosen from the sandbox providers catalog. type: string pvc_size_gi: description: >- Size in GiB of the persistent workspace volume; 0 uses the provider default. format: int64 minimum: 0 type: integer resources: $ref: '#/components/schemas/ManagedAgentsEnvironmentResources' description: >- 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: description: >- Who may use the environment. Defaults to organization, meaning it is shared across the owning organization. type: string secrets: additionalProperties: type: string description: >- 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. type: object setup: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetup' description: >- Setup script run after the sandbox is provisioned and before the agent starts. setup_updated_at: description: RFC 3339 timestamp of the last setup script change. Server-assigned. format: date-time readOnly: true type: string setup_updated_by_user_id: description: User who last changed the setup script. Server-assigned. readOnly: true type: string setup_verification: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupVerification' description: >- 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. readOnly: true setup_warnings: description: >- 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. items: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupWarning' readOnly: true type: array stopped_delete_after_seconds: description: >- Seconds a stopped sandbox is retained before deletion; 0 uses the provider default. format: int64 minimum: 0 type: integer updated_at: description: >- Server-assigned RFC 3339 timestamp of the most recent update to the environment. format: date-time readOnly: true type: string required: - organization_id - environment_id - name - scope - provider - setup - resources - computer_use - created_at - updated_at type: object example: computer_use: true config: key: example created_at: '2026-02-18T09:30:00.000Z' description: example env_vars: key: example environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d http_port: 1 idle_stop_after_seconds: 1 image: example metadata: key: example mounts: - mount_path: example source: example name: example-name network_policy: key: example organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d privileged: true provider: example pvc_size_gi: 1 resources: accelerator: count: 1 name: example-name type: example cpu_milli: 1 memory_mib: 1 placement: allow_spot: true max_price_per_hour_usd: 1.5 min_accelerator_vram_gb: 1 providers: - example regions: - example timeout_seconds: 1 scope: example secrets: key: example setup: script: example timeout_seconds: 1 setup_updated_at: '2026-02-18T09:30:00.000Z' setup_updated_by_user_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d setup_verification: active_setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d at: '2026-02-18T09:30:00.000Z' fingerprint: example image: baseImageDigest: example capturedAt: '2026-02-18T09:30:00.000Z' computeId: example fingerprint: example generation: 1 image: example imageId: example runnerImage: example setupRunId: example sizeBytes: 1 usable: true warmup: example warmupMessage: example imageCapture: at: '2026-02-18T09:30:00.000Z' message: example reason: example setupRunId: example status: failed last_run: duration_ms: 1 exit_code: 1 failed_command: example failed_line: 1 hint: example hint_code: example message: example phase: example setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stderr_tail: example setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d stale: true status: example verified_by_user_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d setup_warnings: - code: example line: 1 message: example stopped_delete_after_seconds: 1 updated_at: '2026-02-18T09:30:00.000Z' ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRevisionConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - revision_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPreconditionFailed: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - precondition_failed message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorSandboxProviderDisabled: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - sandbox_provider_disabled message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPreconditionRequired: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - precondition_required message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvariantViolation: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invariant_violation message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsEnvironmentAccessExpectation: additionalProperties: false description: >- Request-only precondition for changing an environment's access settings. Supply the network policy and effective privileged value from the last environment read; a stale snapshot is rejected. properties: network_policy: additionalProperties: {} description: >- network_policy from the environment read before this PATCH; {} means unrestricted egress. type: object x-lint-ignore: - camel-case-properties privileged: description: >- Effective privileged value from the environment read before this PATCH. type: boolean required: - network_policy - privileged type: object writeOnly: true example: network_policy: key: example privileged: true ManagedAgentsEnvironmentMount: additionalProperties: false description: >- One file or object staged into the sandbox workspace when it is created. Use mounts to give an agent input data it should find already on disk at the first turn. properties: mount_path: description: >- Absolute path inside the sandbox workspace where the source is placed. type: string source: description: Object or file to stage, as a URI the service can read. type: string type: object example: mount_path: example source: example ManagedAgentsEnvironmentResources: additionalProperties: false description: >- Compute sizing and lifetime for an environment's sandbox. CPU environments accept caller-selected CPU and memory. GPU environments accept an exclusive accelerator plus optional lifetime and placement constraints, but use service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory. properties: accelerator: $ref: '#/components/schemas/ManagedAgentsEnvironmentAccelerator' description: >- Exclusive GPU to attach to the sandbox compute. Omit for CPU-only. When set, the service applies limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory, and cpu_milli and memory_mib must be omitted. cpu_milli: description: >- CPU request in millicores, so 1000 is one vCPU; 0 uses the provider default. CPU-only environments; must be omitted with an accelerator because the GPU sandbox CPU limit is service-owned. format: int64 type: integer memory_mib: description: >- Memory request in MiB; 0 uses the provider default. CPU-only environments; must be omitted with an accelerator because the GPU sandbox memory limit is service-owned. format: int64 type: integer placement: $ref: '#/components/schemas/ManagedAgentsEnvironmentPlacement' description: >- Optional region, provider, VRAM, spot, and price constraints. Without an egress policy, omission permits any configured provider. A nonempty Runs network_policy requires GKE; when placement is omitted, the runtime selects GKE without saving a placement constraint. timeout_seconds: description: >- Maximum sandbox lifetime in seconds before the provider tears it down; 0 uses the provider default. format: int64 type: integer type: object example: accelerator: count: 1 name: example-name type: example cpu_milli: 1 memory_mib: 1 placement: allow_spot: true max_price_per_hour_usd: 1.5 min_accelerator_vram_gb: 1 providers: - example regions: - example timeout_seconds: 1 ManagedAgentsEnvironmentSetup: additionalProperties: false description: >- Post-provision customization of a sandbox: a bash script run before the agent starts. Set it when the agent needs packages, tools, or state the runner image does not ship; leave it empty to start from the image as is. Verify it with a setup run before sessions use the environment. properties: script: description: >- Bash script run after the sandbox is provisioned and before the agent starts. When a Runs session's verified captured image has an older runner base, setup runs once on that session's compute. It does not rerun after a container restart or move; a changed container generation prevents further sandbox work in that session. Re-test the environment to capture a compatible image, then start a new session. Executed as a separate login shell with set -eo pipefail, so the first failing line fails the run and is reported by line number; exports and activation do not persist into agent commands. Managed images automatically select a /workspace/.venv created here: install through its explicit interpreter and preserve the existing PATH. Do not wrap lines in bash -lc; the script already runs under bash. Empty means no setup. At most 64 KiB. type: string timeout_seconds: description: >- Wall-clock bound in seconds on the whole script; 0 uses the default of 600. Between 10 and 3600 when set. A run that exceeds it fails with exit code 124. format: int64 type: integer type: object example: script: example timeout_seconds: 1 ManagedAgentsEnvironmentSetupVerification: description: >- Whether an environment's setup script has been proven to run on real compute. Server-owned: it is written by manual setup runs and never accepted from a request body. properties: active_setup_run_id: description: >- Manual setup run in flight for this environment, when there is one. Present alongside any status: a verified environment being re-verified stays verified, and sessions keep starting, until this run finishes. Follow it with getEnvironmentSetupRun or getEnvironmentSetupRunLog. Cleared when the run records a verdict or is cancelled. type: string at: description: RFC 3339 timestamp of when the recorded run finished. format: date-time type: string fingerprint: description: >- Hash of the environment configuration the run executed. Compared against the current configuration to derive stale; opaque to callers. type: string image: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupImage' description: >- Immutable compute image produced after setup passed. Session admission validates this capture and resolves the current runner before choosing to boot it or run setup on the session's compute. imageCapture: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupImageCapture' description: >- Most recent image capture failure. Independent from the setup verdict: setup can be verified while capture failed. last_run: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupRunSummary' description: >- Summary of the recorded run: exit code, failing line and command, stderr tail, and hint. Read hint first when the status is failed; it names the likely fix when the failure is a recognised one. setup_run_id: description: >- Setup run the status was written from. Read its log with getEnvironmentSetupRunLog when the status is failed. type: string stale: description: >- True when the environment's provider, image, compute (resources, workspace disk size, provider config), setup script or timeout, variables, secret references, mounts, network policy, or privileged access changed after the recorded run, so the verdict no longer describes this configuration. Name, description, metadata, and the HTTP port do not count. Re-run setup to clear it. Always false for not_applicable and never. type: boolean status: description: >- not_applicable (no setup script), never (a script exists but no run has recorded a verdict), running (a manual setup run is in flight and there is no earlier passing verdict to stand on), verified (the latest recorded manual run passed), or failed (the latest recorded manual run failed). Sessions on managed providers require verified and not stale when a script is configured; Runs additionally requires a valid captured image. When the captured base differs from the runner resolved at session start, setup runs on the session's compute instead of booting the captured image. The verdict is monotone: re-verifying a verified environment keeps it verified, with the new run in active_setup_run_id, until that run records its own verdict. type: string verified_by_user_id: description: User who requested the recorded run. type: string readOnly: true required: - status - stale type: object example: active_setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d at: '2026-02-18T09:30:00.000Z' fingerprint: example image: baseImageDigest: example capturedAt: '2026-02-18T09:30:00.000Z' computeId: example fingerprint: example generation: 1 image: example imageId: example runnerImage: example setupRunId: example sizeBytes: 1 usable: true warmup: example warmupMessage: example imageCapture: at: '2026-02-18T09:30:00.000Z' message: example reason: example setupRunId: example status: failed last_run: duration_ms: 1 exit_code: 1 failed_command: example failed_line: 1 hint: example hint_code: example message: example phase: example setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stderr_tail: example setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d stale: true status: example verified_by_user_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEnvironmentSetupWarning: description: >- An advisory finding about a setup script line. Warnings never block a save. properties: code: description: >- Stable identifier: bash_lc_wrapper, curl_pipe_sh, unpinned_install, rm_rf_root (line findings); or legacy_setup_discarded (line 0: the stored setup predates setup.script and does not run; re-enter it as a script). type: string line: description: >- 1-based script line the finding is on; 0 when the finding is about the save rather than a line. format: int64 type: integer message: description: What was found and the recommended change. type: string required: - code - line - message type: object example: code: example line: 1 message: example ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: {} description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. ManagedAgentsEnvironmentAccelerator: additionalProperties: false description: >- An accelerator attached to an environment's sandbox compute. Set it only for GPU workloads; omit it and the sandbox runs CPU-only. A GPU sandbox receives one exclusive accelerator with service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory; its host machine may be larger. properties: count: description: >- How many accelerators to attach. Defaults to 1; every offering currently carries one. format: int64 type: integer name: description: >- Accelerator model, lower-case and provider-neutral, e.g. a100. Must name a model in this deployment's configured accelerator_catalog. Live compute offerings enrich that catalog but never remove configured choices. type: string type: description: Accelerator class to attach. Only gpu is accepted. type: string type: object example: count: 1 name: example-name type: example ManagedAgentsEnvironmentPlacement: additionalProperties: false description: >- Where an environment's sandboxes may run, expressed as constraints rather than a named machine. The runtime selects a provider that can enforce the environment's access settings. properties: allow_spot: description: >- Let preemptible capacity compete on price. A reclaimed sandbox is failed and restarted from its last snapshot rather than resumed in place, so this trades an occasional lost turn for markedly cheaper accelerators. type: boolean max_price_per_hour_usd: description: >- Reject offerings priced above this per hour. Offerings whose price is unknown are never rejected by this, because an unpriced offering is a gap in a provider's catalog rather than an expensive machine. format: double type: number min_accelerator_vram_gb: description: >- Reject offerings whose per-accelerator memory is below this, in vendor-quoted gigabytes. Omit unless a workload genuinely needs the larger variant: an H100 and an H200 run the same image and the same snapshot, so treating them as interchangeable is what makes capacity findable. format: int64 type: integer providers: description: >- Restrict placement to these providers, e.g. gke or nebius. Empty permits configured providers compatible with the environment's network policy and privileged access. A nonempty Runs network_policy requires gke. items: type: string type: array regions: description: >- Regions the sandbox may run in, as each provider names them. Empty means anywhere the deployment has configured, which is the usual answer: constraining regions constrains capacity, and capacity is the reason to place across providers at all. items: type: string type: array type: object example: allow_spot: true max_price_per_hour_usd: 1.5 min_accelerator_vram_gb: 1 providers: - example regions: - example ManagedAgentsEnvironmentSetupImage: description: >- An immutable setup image published after a manual setup run passes. Identity includes the environment fingerprint, configured runner, observed base digest, and capture generation. properties: baseImageDigest: description: Immutable base image reference observed by Agent Service. type: string capturedAt: description: When Agent Service reported the image ready. format: date-time type: string computeId: description: Agent Service compute whose filesystem was captured. type: string fingerprint: description: Environment configuration fingerprint this image was produced for. type: string generation: description: Capture and boot contract generation. format: int64 type: integer image: description: Immutable digest-pinned image reference. type: string imageId: description: Agent Service image id. type: string runnerImage: description: Exact configured runner reference selected for the captured compute. type: string setupRunId: description: Manual setup run that produced this image. type: string sizeBytes: description: Captured filesystem layer size. format: int64 type: integer usable: description: >- Registry-free read-time projection for the active verified environment and configured runner. A moving tag may have changed since this projection; session admission resolves its exact digest before choosing the captured image or per-session setup. type: boolean warmup: description: >- Agent Service warmup state: pulling, verifying, ready, failed, or unavailable. type: string warmupMessage: description: Bounded Agent Service explanation of the warmup state. type: string required: - imageId - computeId - setupRunId - image - baseImageDigest - fingerprint - runnerImage - generation - sizeBytes - capturedAt type: object example: baseImageDigest: example capturedAt: '2026-02-18T09:30:00.000Z' computeId: example fingerprint: example generation: 1 image: example imageId: example runnerImage: example setupRunId: example sizeBytes: 1 usable: true warmup: example warmupMessage: example ManagedAgentsEnvironmentSetupImageCapture: description: Why a verified setup run published no new reusable image. properties: at: description: When the capture failure was recorded. format: date-time type: string message: description: Sanitized bounded explanation. type: string reason: description: Stable Agent Service capture failure reason. type: string setupRunId: description: Setup run whose capture failed. type: string status: description: Always failed; successful capture is represented by image. enum: - failed type: string required: - status - setupRunId - at type: object example: at: '2026-02-18T09:30:00.000Z' message: example reason: example setupRunId: example status: failed ManagedAgentsEnvironmentSetupRunSummary: description: >- The outcome of one setup run, reduced to what a caller needs to fix it: exit code, failing line, stderr tail, and a hint when the cause is recognised. properties: duration_ms: description: >- Wall-clock duration of the run in milliseconds, provisioning included. format: int64 type: integer exit_code: description: >- Exit code of the setup script when it ran. 124 means the timeout elapsed; absent when the run failed before the script started. type: integer failed_command: description: >- The failing line's command as written in the script, unexpanded, so it never contains a secret's value. type: string failed_line: description: >- 1-based line in the setup script whose command exited non-zero. 0 when unknown. format: int64 type: integer hint: description: >- Human-readable likely fix for a recognised failure cause. Absent rather than guessed when the cause is not recognised. type: string hint_code: description: >- Stable identifier of the recognised failure cause, e.g. command_not_found, pip_not_installed, bash_lc_wrapper, egress_blocked, timeout. Absent when the cause was not recognised. type: string message: description: One-sentence description of the outcome suitable for showing as is. type: string phase: description: >- Phase the run ended in: provision, gpu_check, setup, profile, commit, or cleanup. A failure outside setup is about the platform, not the script. type: string setup_run_id: description: Setup run this summary describes. type: string status: description: succeeded, failed, or cancelled. type: string stderr_tail: description: Last lines of stderr from the script, redacted and bounded to 2 KiB. type: string required: - setup_run_id - status type: object example: duration_ms: 1 exit_code: 1 failed_command: example failed_line: 1 hint: example hint_code: example message: example phase: example setup_run_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stderr_tail: example securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````