> ## Documentation Index > Fetch the complete documentation index at: https://trueforge.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a sandbox environment > Create or replace by `manifest.name`. Requires a configured sandbox provider. ## OpenAPI ````yaml /openapi.json put /api/v1/sandbox-environments openapi: 3.1.0 info: description: >- HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`). **Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them. Covers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers. title: TrueForge API version: 0.0.0 servers: [] security: - BearerAuth: [] tags: - name: Internal - name: Auth - name: Capabilities - name: Models - name: MCP Servers - name: Skills - name: Sandboxes - name: Web Search Providers - name: Agents - name: Schedules - name: Agent Sessions paths: /api/v1/sandbox-environments: put: tags: - Sandboxes summary: Create or update a sandbox environment description: >- Create or replace by `manifest.name`. Requires a configured sandbox provider. requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSandboxEnvironmentRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetSandboxEnvironmentResponse' description: The saved sandbox environment. '400': content: application/json: schema: $ref: '#/components/schemas/RequestErrorResponse' description: Invalid request body, or missing secret value. '401': content: application/json: schema: $ref: '#/components/schemas/RequestErrorResponse' description: Unauthenticated. '409': content: application/json: schema: $ref: '#/components/schemas/RequestErrorResponse' description: Name conflict or concurrent update. '422': content: application/json: schema: $ref: '#/components/schemas/RequestErrorResponse' description: Sandbox provider is missing or its credentials are invalid. '502': content: application/json: schema: $ref: '#/components/schemas/RequestErrorResponse' description: Sandbox provider secret synchronization failed. components: schemas: UpdateSandboxEnvironmentRequest: additionalProperties: false properties: manifest: $ref: '#/components/schemas/SandboxEnvironmentManifestRequest' required: - manifest type: object GetSandboxEnvironmentResponse: properties: data: $ref: '#/components/schemas/SandboxEnvironment' required: - data type: object RequestErrorResponse: properties: error: properties: code: description: Optional machine-readable error code; null when not applicable. type: - string - 'null' message: description: Human-readable explanation of the failure. type: string param: description: >- Optional request field that caused the error; null when not field-specific. type: - string - 'null' type: description: Optional error category (e.g. validation vs conflict). type: string required: - message type: object required: - error type: object SandboxEnvironmentManifestRequest: additionalProperties: false properties: description: description: Optional human-readable description. maxLength: 1024 type: string environment_variables: additionalProperties: type: string type: object image: $ref: '#/components/schemas/SandboxEnvironmentImage' name: $ref: '#/components/schemas/ResourceName' networking: $ref: '#/components/schemas/SandboxEnvironmentNetworking' resources: $ref: '#/components/schemas/SandboxEnvironmentResources' required: - name type: object SandboxEnvironment: additionalProperties: false properties: created_at: description: ISO-8601 create time. format: date-time type: string created_by_subject: $ref: '#/components/schemas/CreatedBySubject' description: description: Human-readable description; empty when unset. type: string id: description: Immutable server-generated environment identifier. minLength: 1 type: string lifecycle_stage: $ref: '#/components/schemas/SandboxEnvironmentLifecycleStage' manifest: $ref: '#/components/schemas/SandboxEnvironmentManifest' name: $ref: '#/components/schemas/ResourceName' status: $ref: '#/components/schemas/SandboxEnvironmentVersionStatus' status_reason: description: Failure detail when status is failed; null otherwise. type: - string - 'null' updated_at: description: ISO-8601 last update time. format: date-time type: string required: - id - name - description - lifecycle_stage - status - status_reason - manifest - created_by_subject - created_at - updated_at type: object SandboxEnvironmentImage: additionalProperties: false properties: build_script: description: Shell script used to build the snapshot. example: | set -ex pip install httpx minLength: 1 type: string type: description: Build a snapshot from a script. enum: - build type: string required: - type type: object ResourceName: maxLength: 64 minLength: 2 pattern: ^[a-z][a-z0-9-]{0,62}[a-z0-9]$ type: string SandboxEnvironmentNetworking: additionalProperties: false properties: domain_allow_list: description: Comma-separated allowed domains. minLength: 1 type: string network_block_all: description: >- Block all outbound network access. When true, domain_allow_list and secrets are not used. type: boolean secrets: description: Network-scoped secrets. items: $ref: '#/components/schemas/SandboxEnvironmentSecret' type: array type: object SandboxEnvironmentResources: additionalProperties: false default: cpu: 1 disk: 3 memory: 1 properties: cpu: default: 1 description: CPU allocation in cores. exclusiveMinimum: 0 type: number disk: default: 3 description: Disk allocation in GiB. exclusiveMinimum: 0 type: number memory: default: 1 description: Memory allocation in GiB. exclusiveMinimum: 0 type: number type: object CreatedBySubject: additionalProperties: false description: Who created this resource. properties: subject_display_name: description: Display name. minLength: 1 type: string subject_id: description: Subject id. minLength: 1 type: string subject_type: description: Subject type. minLength: 1 type: string required: - subject_id - subject_type - subject_display_name type: object SandboxEnvironmentLifecycleStage: description: Soft-delete lifecycle stage. enum: - active - deleted type: string SandboxEnvironmentManifest: additionalProperties: false properties: description: description: Optional human-readable description. maxLength: 1024 type: string environment_variables: additionalProperties: type: string type: object image: $ref: '#/components/schemas/SandboxEnvironmentImage' name: $ref: '#/components/schemas/ResourceName' networking: $ref: '#/components/schemas/SandboxEnvironmentNetworking' resources: $ref: '#/components/schemas/SandboxEnvironmentResources' required: - name type: object SandboxEnvironmentVersionStatus: description: Readiness of the environment. enum: - pending - ready - failed type: string SandboxEnvironmentSecret: additionalProperties: false properties: env: description: Environment variable name injected into the sandbox. minLength: 1 type: string hosts: description: Hosts this secret may be sent to. items: minLength: 1 type: string type: array value: description: Secret value; GET responses use a redacted stand-in. minLength: 1 type: string required: - env - value - hosts type: object securitySchemes: BearerAuth: bearerFormat: JWT description: >- Caller credential (`Authorization: Bearer `). Required on protected routes when auth is enabled. Browser sessions may use the HttpOnly `id_token` or `accessToken` cookie instead. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.