> ## 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. # 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. Privileged Docker requires unrestricted internet access (network_policy: {}). 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. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/environments 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: post: tags: - Environments summary: Create environment description: >- 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. Privileged Docker requires unrestricted internet access (network_policy: {}). 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. operationId: managedAgentsCreateEnvironment parameters: - 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 - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEnvironmentRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Environment' 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 recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '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 recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Conflict. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress discriminator: propertyName: code mapping: idempotency_conflict: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress x-recursion-error-codes: - idempotency_conflict - idempotency_in_progress '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '422': description: Unprocessable Entity. content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsApiErrorSandboxProviderDisabled x-recursion-error-codes: - sandbox_provider_disabled headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorComputeOfferingsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorComputeOfferingsUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: compute_offerings_unavailable: >- #/components/schemas/ManagedAgentsApiErrorComputeOfferingsUnavailable compute_offerings_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorComputeOfferingsUnconfigured idempotency_unavailable: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - compute_offerings_unavailable - compute_offerings_unconfigured - idempotency_unavailable - managed_agents_unavailable - service_unavailable headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- 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`. schema: type: string minLength: 1 schemas: CreateEnvironmentRequest: additionalProperties: false description: >- 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. properties: computer_use: description: >- Enable the shared interactive browser display. The server sets http_port to 6901; false disables it. type: boolean config: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: Provider-specific overflow config. type: object description: description: Optional free-text note about what this environment is for. type: string env_vars: additionalProperties: type: string description: >- Environment variables injected into the sandbox. Each name must be letters, digits and underscores, not starting with a digit. type: object http_port: description: >- TCP port inside the sandbox that the provider exposes for HTTP traffic. Omit or send 0 if the workload serves nothing. format: int64 maximum: 65535 minimum: 0 type: integer idle_stop_after_seconds: description: >- Seconds of inactivity before compute stops, from 120 through 7200 (2 hours); omit or send 0 for the provider default. Computer use requires 0 or at least 600 seconds. format: int64 maximum: 7200 minimum: 0 type: integer metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Free-form caller-owned JSON stored with the environment and returned on reads. Not interpreted by the service. type: object mounts: description: Files staged into the sandbox workspace on create. items: $ref: '#/components/schemas/EnvironmentMount' type: array name: description: >- Human-readable label for the environment. Required, and not blank; surrounding whitespace is trimmed. maxLength: 256 type: string network_policy: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Internet access for Runs environments. Omit for No access; send {} for unrestricted access. A nonempty policy limits destinations and cannot be combined with privileged Docker. If the selected placement is incompatible, choose a compatible placement or send {} for unrestricted access. type: object x-recursion-omission: source: >- Omitting network_policy sets No access ({"version":"v1","rules":[]}). If the selected placement is incompatible, choose a compatible placement or send network_policy: {} for unrestricted internet access. strategy: derive privileged: description: >- Whether the Runs sandbox may use privileged Docker. Defaults to false. Privileged Docker requires unrestricted internet access: send network_policy: {} rather than omitting it. type: boolean x-recursion-omission: source: >- New Runs environments derive privileged: false. Docker environments do not use this setting. strategy: derive provider: description: >- Environment runtime: runs (managed agent runner) or docker (local development). Any other value is rejected, including the retired self_hosted and rma names. type: string pvc_size_gi: description: >- Persistent workspace size in GiB, from 1 through 100; omit or send 0 for the provider default. format: int64 maximum: 100 minimum: 0 type: integer resources: $ref: '#/components/schemas/EnvironmentResourcesRequest' description: >- Compute 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. scope: description: >- Visibility of the environment record within the organization. organization is the only value; it is also the default when omitted. type: string secrets: additionalProperties: type: string description: >- 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. type: object setup: $ref: '#/components/schemas/EnvironmentSetupRequest' description: >- Setup script run once on fresh compute after the sandbox is provisioned, before the agent starts. Verify it with managedAgentsCreateEnvironmentSetupRun before starting sessions. stopped_delete_after_seconds: description: >- Seconds after a sandbox stops before it may be released, from 3600 (an hour) to 2592000 (30 days). This does not expire the session. Send another message to resume it; /workspace files can be used when its workspace reopens. Omit or send 0 to use the service default. format: int64 minimum: 0 type: integer maximum: 9007199254740991 template: $ref: '#/components/schemas/TemplateRef' description: >- Reviewed environment template id and revision used to prefill this create request. required: - name - provider type: object allOf: - if: properties: resources: anyOf: - required: - accelerator - required: - cpu_milli - required: - memory_mib - required: - placement - required: - timeout_seconds required: - resources then: properties: provider: const: runs - if: properties: resources: properties: accelerator: $ref: '#/components/schemas/PlatformSafeJsonValue' required: - accelerator required: - resources then: properties: provider: const: runs - if: properties: network_policy: type: object minProperties: 1 required: - network_policy then: properties: resources: properties: placement: properties: providers: const: - gke Environment: 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: $ref: '#/components/schemas/PlatformSafeJsonValue' 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; store them as vault credentials 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 maximum: 9007199254740991 idle_stop_after_seconds: description: >- 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. format: int64 minimum: 0 type: integer maximum: 9007199254740991 image: description: >- Container image the sandbox boots. Set by the platform: new environments use the default runner image. Customize the sandbox itself with setup.script. type: string readOnly: true metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' 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/EnvironmentMount' type: array name: description: Human-readable label shown wherever environments are listed. type: string network_policy: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- 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. 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. 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. 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 maximum: 9007199254740991 resources: $ref: '#/components/schemas/EnvironmentResources' 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: >- 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. type: object setup: $ref: '#/components/schemas/EnvironmentSetup' 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/EnvironmentSetupVerification' description: >- 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. 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/EnvironmentSetupWarning' readOnly: true type: array stopped_delete_after_seconds: description: >- 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. format: int64 minimum: 0 type: integer maximum: 9007199254740991 template: $ref: '#/components/schemas/TemplateRef' description: Reviewed template revision used to create this environment. 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 additionalProperties: false 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. 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. 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. ManagedAgentsApiErrorDependencyFailure: 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. ManagedAgentsApiErrorComputeOfferingsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - compute_offerings_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. ManagedAgentsApiErrorComputeOfferingsUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - compute_offerings_unconfigured 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. ManagedAgentsApiErrorDependencyTimeout: 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. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object EnvironmentMount: 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 EnvironmentResourcesRequest: additionalProperties: false description: Caller-supplied environment compute sizing and lifetime constraints. properties: accelerator: $ref: '#/components/schemas/EnvironmentAcceleratorRequest' description: Exclusive GPU request. Omit for CPU-only compute. cpu_milli: type: integer format: int64 anyOf: - const: 0 - minimum: 250 maximum: 8000 maximum: 8000 description: >- CPU millicores. Omit or send 0 for the provider default; otherwise 250 through 8000. minimum: -9007199254740991 memory_mib: type: integer format: int64 anyOf: - const: 0 - minimum: 1024 maximum: 32768 maximum: 32768 description: >- Memory in MiB. Omit or send 0 for the provider default; otherwise 1024 through 32768. minimum: -9007199254740991 placement: $ref: '#/components/schemas/EnvironmentPlacementRequest' description: Optional canonical placement constraints. timeout_seconds: type: integer format: int64 anyOf: - const: 0 - minimum: 10 maximum: 86400 description: >- Maximum sandbox lifetime. Omit or send 0 for the provider default; otherwise 10 to 86400 seconds. minimum: -9007199254740991 maximum: 9007199254740991 type: object allOf: - if: required: - accelerator then: properties: cpu_milli: const: 0 memory_mib: const: 0 EnvironmentSetupRequest: additionalProperties: false description: Caller-supplied post-provision setup script and timeout. properties: script: type: string pattern: ^[^\u0000]*$ description: >- Bash setup script. UTF-8 encoding must be at most 65,536 bytes and contain no NUL. timeout_seconds: type: integer format: int64 anyOf: - const: 0 - minimum: 10 maximum: 3600 description: >- Setup timeout. Omit or send 0 for the default; otherwise 10 to 3600 seconds. minimum: -9007199254740991 maximum: 9007199254740991 type: object TemplateRef: description: Reviewed template id and revision copied into this resource. properties: id: description: Stable template id. type: string revision: description: Reviewed catalog revision. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision type: object additionalProperties: false EnvironmentResources: 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/EnvironmentAccelerator' 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 minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 placement: $ref: '#/components/schemas/EnvironmentPlacement' 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 minimum: -9007199254740991 maximum: 9007199254740991 type: object EnvironmentSetup: 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. Runs sessions boot from a captured setup image; when the runner changes, the platform runs this script on dedicated setup compute and captures a new image before provisioning the 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 minimum: -9007199254740991 maximum: 9007199254740991 type: object EnvironmentSetupVerification: description: >- Whether an environment's setup script has been proven to run on real compute. Server-owned: it is written by manual or automatic setup runs and never accepted from a request body. properties: active_setup_run_id: description: >- Manual or automatic 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 managedAgentsGetEnvironmentSetupRun or managedAgentsGetEnvironmentSetupRunLog. 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/EnvironmentSetupImage' description: >- Immutable compute image produced after setup passed. Session admission validates this capture and resolves the current runner before choosing to boot it or wait for an automatic runner_refresh capture. imageCapture: $ref: '#/components/schemas/EnvironmentSetupImageCapture' description: >- Most recent image capture failure. Independent from the setup verdict: setup can be verified while capture failed. last_run: $ref: '#/components/schemas/EnvironmentSetupRunSummary' 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 managedAgentsGetEnvironmentSetupRunLog 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, retired 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 setup run is in flight and there is no earlier passing verdict to stand on), verified (the latest recorded run passed), or failed (the latest recorded 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, a runner_refresh setup run captures a matching image before session provisioning. 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 additionalProperties: false EnvironmentSetupWarning: 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 minimum: -9007199254740991 maximum: 9007199254740991 message: description: What was found and the recommended change. type: string required: - code - line - message type: object additionalProperties: false 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: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. EnvironmentAcceleratorRequest: additionalProperties: false description: >- One exclusive GPU requested for an environment. The model name must come from the deployment catalog. properties: count: type: integer format: int64 enum: - 0 - 1 description: One accelerator is attached. Omit or send 0 to select that default. minimum: -9007199254740991 maximum: 9007199254740991 name: type: string minLength: 1 description: >- Nonempty provider-neutral accelerator model from the deployment catalog. type: type: string const: gpu description: Accelerator class. Omit to select gpu, or send gpu explicitly. type: object required: - name EnvironmentPlacementRequest: additionalProperties: false description: >- Canonical environment placement request. Exactly one supported provider is selected; regions, spot capacity, VRAM floors, and caller-supplied price limits are not supported. properties: allow_spot: type: boolean const: false description: Spot capacity is not supported and must be false when sent. max_price_per_hour_usd: type: number format: double const: 0 description: >- Caller-supplied price limits are not supported and must be zero when sent. min_accelerator_vram_gb: type: integer format: int64 const: 0 description: >- Caller-supplied VRAM floors are not supported and must be zero when sent. minimum: -9007199254740991 maximum: 9007199254740991 providers: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: string enum: - gke - nebius description: Exactly one supported compute provider. regions: type: array maxItems: 0 items: type: string description: >- Region constraints are not supported and this array must be empty when sent. type: object required: - providers EnvironmentAccelerator: 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 minimum: -9007199254740991 maximum: 9007199254740991 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 EnvironmentPlacement: 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 minimum: -9007199254740991 maximum: 9007199254740991 providers: description: >- Select exactly one provider, gke or nebius, when placement is present. Omit placement to let the system choose. Limited internet access is available only with 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 EnvironmentSetupImage: description: >- An immutable setup image published after a manual or automatic 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 minimum: -9007199254740991 maximum: 9007199254740991 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 or automatic setup run that produced this image. type: string sizeBytes: description: Captured filesystem layer size. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 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 a runner refresh. 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 additionalProperties: false EnvironmentSetupImageCapture: 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 additionalProperties: false EnvironmentSetupRunSummary: 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 minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 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 additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````