> ## 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 (networkPolicy: {}). 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/v2/environments openapi: 3.1.0 info: title: Managed Agents API version: 0.15.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/v2/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 (networkPolicy: {}). 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: managedAgentsCreateEnvironmentV2 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/StandaloneV2CreateEnvironmentRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/StandaloneV2Environment' description: A standalone sandbox environment a session executes in. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple Location: description: Relative URL of the created resource. schema: type: string 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: StandaloneV2CreateEnvironmentRequest: additionalProperties: false description: Request body for creating a standalone environment. properties: computerUse: description: >- Enable the shared interactive browser display. The server sets httpPort to 6901; false disables it. type: boolean x-recursion-omission: source: Computer use is disabled by default. strategy: derive config: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: Provider-specific overflow config. type: object x-recursion-omission: strategy: absent description: description: Optional free-text note about what this environment is for. type: string x-recursion-omission: strategy: absent envVars: 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 x-recursion-omission: source: An omitted environment has no caller variables. strategy: derive httpPort: 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 x-recursion-omission: source: An omitted HTTP port disables service exposure. strategy: derive idleStopAfterSeconds: description: >- Seconds of inactivity after which the sandbox is stopped, from 120 to 2592000 (30 days). Omit or send 0 to use the provider's lifecycle policy instead of a per-environment one. Computer use requires 0 or at least 600 seconds. format: int64 maximum: 7200 minimum: 0 type: integer x-recursion-omission: source: The provider selects its default idle timeout. strategy: derive 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 x-recursion-omission: strategy: absent mounts: description: Files staged into the sandbox workspace on create. items: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentMountRequest' type: array x-recursion-omission: strategy: absent name: description: >- Human-readable label for the environment. Required, and not blank; surrounding whitespace is trimmed. maxLength: 256 type: string networkPolicy: 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 networkPolicy sets No access ({"version":"v1","rules":[]}). strategy: derive privileged: description: >- Whether the Runs sandbox may use privileged Docker. Defaults to false. Privileged Docker requires unrestricted internet access: send networkPolicy: {} rather than omitting it. type: boolean x-recursion-omission: source: 'New Runs environments derive privileged: false.' 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 pvcSizeGi: description: >- Size in gibibytes of the persistent volume attached to the sandbox workspace, from 1 to 1000. Omit or send 0 to let the sandbox provider choose. format: int64 maximum: 100 minimum: 0 type: integer x-recursion-omission: source: The provider selects its default workspace size. strategy: derive resources: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentResourcesRequest' description: >- Compute sizing: cpuMilli and memoryMib 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. x-recursion-omission: source: The provider selects its default compute resources. strategy: derive scope: description: >- Visibility of the environment record within the organization. organization is the only value; it is also the default when omitted. type: string x-recursion-omission: source: The caller's organization owns the environment. strategy: derive 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 references. type: object x-recursion-omission: strategy: absent setup: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentSetupRequest' description: >- Setup script run once on fresh compute after the sandbox is provisioned, before the agent starts. Verify it with managedAgentsCreateEnvironmentSetupRunV2 before starting sessions. x-recursion-omission: source: An omitted setup has no script. strategy: derive stoppedDeleteAfterSeconds: 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 x-recursion-omission: source: The service selects its default stopped retention. strategy: derive maximum: 9007199254740991 template: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentTemplateRefRequest' description: >- Reviewed environment template id and revision used to prefill this create request. x-recursion-omission: strategy: absent required: - name - provider type: object StandaloneV2Environment: description: A standalone sandbox environment a session executes in. properties: computerUse: description: >- Whether this environment boots the shared interactive Chromium display used by the computer and human-handoff tools. The server projects this to httpPort 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 createdAt: 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 envVars: 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 environmentId: description: >- Server-assigned id of the environment; pass it when starting a session that should run in this sandbox. readOnly: true type: string httpPort: 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 idleStopAfterSeconds: 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. 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 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/StandaloneV2EnvironmentMount' type: array name: description: Human-readable label shown wherever environments are listed. type: string networkPolicy: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Internet access for Runs environments. An empty object means unrestricted access. type: object organizationId: 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 (networkPolicy: {}) on create or when changing access settings. Omit on update to keep the current value, or send false to disable it. New Runs environments and transitions from another provider default to false. Existing environments with both limited internet access and privileged Docker remain visible and allow edits to other settings. To start a new session, set networkPolicy: {} or disable privileged Docker. type: boolean provider: description: >- Sandbox runtime that executes the session, chosen from the sandbox providers catalog. type: string pvcSizeGi: 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/StandaloneV2EnvironmentResources' 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/StandaloneV2EnvironmentSetup' description: >- Setup script run after the sandbox is provisioned and before the agent starts. setupUpdatedAt: description: RFC 3339 timestamp of the last setup script change. Server-assigned. format: date-time readOnly: true type: string setupUpdatedByUserId: description: User who last changed the setup script. Server-assigned. readOnly: true type: string setupVerification: $ref: '#/components/schemas/StandaloneV2EnvironmentSetupVerification' 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 lastRun.hint first when status is failed. readOnly: true setupWarnings: 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 stoppedDeleteAfterSeconds: 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. updatedAt: description: >- Server-assigned RFC 3339 timestamp of the most recent update to the environment. format: date-time readOnly: true type: string required: - organizationId - environmentId - name - scope - provider - setup - resources - computerUse - createdAt - updatedAt 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 StandaloneV2CreateEnvironmentMountRequest: additionalProperties: false properties: mountPath: description: >- Absolute path inside the sandbox workspace where the source is placed. type: string x-recursion-omission: strategy: absent source: description: Object or file to stage, as a URI the service can read. type: string x-recursion-omission: strategy: absent type: object StandaloneV2CreateEnvironmentResourcesRequest: additionalProperties: false description: Compute sizing and lifetime for a standalone environment sandbox. properties: accelerator: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentAcceleratorRequest' description: Exclusive GPU for this sandbox; omit for CPU-only. x-recursion-omission: strategy: absent cpuMilli: description: CPU request in millicores; 0 uses the provider default. format: int64 maximum: 24000 minimum: 0 type: integer x-recursion-omission: source: The provider supplies its default CPU size. strategy: derive memoryMib: description: Memory request in MiB; 0 uses the provider default. format: int64 maximum: 102400 minimum: 0 type: integer x-recursion-omission: source: The provider supplies its default memory size. strategy: derive placement: $ref: '#/components/schemas/StandaloneV2CreateEnvironmentPlacementRequest' description: Optional provider, region, VRAM, spot, and price constraints. x-recursion-omission: strategy: absent timeoutSeconds: description: Maximum sandbox lifetime in seconds; 0 uses the provider default. format: int64 type: integer x-recursion-omission: source: The provider supplies its default lifetime. strategy: derive minimum: -9007199254740991 maximum: 9007199254740991 type: object x-recursion-omission: source: The provider selects its default compute resources. strategy: derive StandaloneV2CreateEnvironmentSetupRequest: additionalProperties: false 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 x-recursion-omission: source: No setup script runs when the field is omitted. strategy: derive timeoutSeconds: 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 x-recursion-omission: source: The setup timeout defaults to 600 seconds. strategy: derive minimum: -9007199254740991 maximum: 9007199254740991 type: object x-recursion-omission: source: An omitted setup has no script. strategy: derive StandaloneV2CreateEnvironmentTemplateRefRequest: properties: id: description: Stable template id. type: string revision: description: Reviewed catalog revision. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision type: object x-recursion-omission: strategy: absent additionalProperties: false StandaloneV2EnvironmentMount: additionalProperties: false properties: mountPath: 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 StandaloneV2EnvironmentResources: additionalProperties: false 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 cpuMilli and memoryMib must be omitted. cpuMilli: 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 memoryMib: 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/StandaloneV2EnvironmentPlacement' description: >- Optional region, provider, VRAM, spot, and price constraints. Without an egress policy, omission permits any configured provider. A nonempty Runs networkPolicy requires GKE; when placement is omitted, the runtime selects GKE without saving a placement constraint. timeoutSeconds: 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 StandaloneV2EnvironmentSetup: additionalProperties: false 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 timeoutSeconds: 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 StandaloneV2EnvironmentSetupVerification: description: Server-owned verdict on the environment setup script. properties: activeSetupRunId: 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 managedAgentsGetEnvironmentSetupRunV2 or managedAgentsGetEnvironmentSetupRunLogV2. 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. lastRun: $ref: '#/components/schemas/StandaloneV2EnvironmentSetupRunSummary' 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. setupRunId: description: >- Setup run the status was written from. Read its log with managedAgentsGetEnvironmentSetupRunLogV2 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 activeSetupRunId, until that run records its own verdict. type: string verifiedByUserId: 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 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 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. StandaloneV2CreateEnvironmentAcceleratorRequest: additionalProperties: false properties: count: description: >- How many accelerators to attach. Defaults to 1; every offering currently carries one. format: int64 type: integer x-recursion-omission: strategy: absent 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 x-recursion-omission: strategy: absent type: description: Accelerator class to attach. Only gpu is accepted. type: string x-recursion-omission: strategy: absent type: object x-recursion-omission: strategy: absent StandaloneV2CreateEnvironmentPlacementRequest: additionalProperties: false properties: allowSpot: 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 x-recursion-omission: strategy: absent maxPricePerHourUsd: 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 x-recursion-omission: strategy: absent minAcceleratorVramGb: 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 x-recursion-omission: strategy: absent 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 x-recursion-omission: strategy: absent 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 x-recursion-omission: strategy: absent type: object x-recursion-omission: strategy: absent 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 StandaloneV2EnvironmentPlacement: additionalProperties: false properties: allowSpot: 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 maxPricePerHourUsd: 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 minAcceleratorVramGb: 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 StandaloneV2EnvironmentSetupRunSummary: properties: durationMs: description: >- Wall-clock duration of the run in milliseconds, provisioning included. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 exitCode: 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 failedCommand: description: >- The failing line's command as written in the script, unexpanded, so it never contains a secret's value. type: string failedLine: 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 hintCode: 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 setupRunId: description: Setup run this summary describes. type: string status: description: succeeded, failed, or cancelled. type: string stderrTail: description: Last lines of stderr from the script, redacted and bounded to 2 KiB. type: string required: - setupRunId - 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. ````