> ## Documentation Index > Fetch the complete documentation index at: https://docs.baseten.co/llms.txt > Use this file to discover all available pages before exploring further. # Update a sandbox > Updates the configuration of a sandbox. Omitted fields remain unchanged. Supplied arrays and maps replace their previous values; structured objects update only the fields you supply. You can update `lifecycle`, `envs`, `external_id`, and `labels`. The sandbox name, image, memory, and region are immutable; to use a different image, create a new sandbox. Related guide: [Manage sandboxes](/sandboxes/manage#manage-a-sandboxs-labels). ## OpenAPI ````yaml patch /v1/sandboxes/instances/{sandbox_name} openapi: 3.1.0 info: description: REST API for management of Baseten resources title: Baseten management API version: 1.0.0 servers: - url: https://api.baseten.co security: - BearerAuth: [] paths: /v1/sandboxes/instances/{sandbox_name}: parameters: - $ref: '#/components/parameters/SandboxName' patch: tags: - Sandboxes summary: Update a sandbox description: >- Partially update configuration. Omitted fields remain unchanged; supplied arrays and maps replace their previous values. Structured objects update only supplied fields. The name, memory, network, region, image, and ports are immutable after creation. Supplying any of these fields returns 400, including unchanged, empty, or null values. operationId: UpdateSandbox parameters: - $ref: '#/components/parameters/TeamId' - $ref: '#/components/parameters/TeamIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSandboxRequestV1' examples: complete: $ref: '#/components/examples/UpdateSandbox' responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/SandboxV1' examples: complete: $ref: '#/components/examples/SandboxUpdated' '400': description: >- Invalid request, including attempts to change memory or network configuration. content: application/json: example: code: INVALID_REQUEST message: >- Memory and network configuration cannot be changed after creation. '401': $ref: '#/components/responses/SandboxError401' '403': $ref: '#/components/responses/SandboxError403' '404': $ref: '#/components/responses/SandboxError404' '409': $ref: '#/components/responses/SandboxError409' '429': $ref: '#/components/responses/SandboxError429' '500': $ref: '#/components/responses/SandboxError500' components: parameters: SandboxName: name: sandbox_name in: path required: true description: Immutable sandbox name returned by creation. schema: type: string minLength: 1 example: baseten-api-review-0916 TeamId: name: team_id in: query required: false description: >- Optional team ID. Must match X-Team-Id when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string TeamIdHeader: name: X-Team-Id in: header required: false description: >- Optional team ID. Must match the team_id query parameter when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string schemas: UpdateSandboxRequestV1: type: object description: >- Partial sandbox update. Omitted fields remain unchanged. Supplied arrays and maps (including labels) replace their previous values; supplied structured objects update only their supplied fields. Null is not accepted. The name, memory, network, region, image, and ports are immutable after creation. Supplying any of these fields returns 400, including unchanged, empty, or null values. properties: lifecycle: description: >- Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates allOf: - $ref: '#/components/schemas/SandboxLifecycleV1' example: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h envs: type: array description: Environment variables injected into the sandbox. items: $ref: '#/components/schemas/SandboxEnvV1' example: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' external_id: type: string description: >- Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash. example: api-review-20260916-001 maxLength: 64 pattern: ^[A-Za-z0-9-]+$ labels: description: >- Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy. allOf: - $ref: '#/components/schemas/SandboxMetadataLabelsV1' example: env: development project: api-review team: engineering revision: '2' minProperties: 1 example: lifecycle: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h envs: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' external_id: api-review-20260916-001 labels: env: development project: api-review team: engineering revision: '2' SandboxV1: description: >- Sandbox resource with configuration and server-managed fields at the root. No metadata, spec, or runtime wrapper. allOf: - $ref: '#/components/schemas/SandboxConfigurationV1' - type: object description: Server-managed sandbox fields. properties: name: type: string description: >- Immutable sandbox name, provided by the client or generated by the server, used in sandbox_name path parameters. readOnly: true example: baseten-api-review-0916 url: type: string description: >- Base URL of this sandbox's execution API, always present on successful creation. The URL is assigned before deployment completes; inspect status for readiness. Use this exact returned URL; do not reconstruct its hostname. Authenticate requests with your authentication token using Authorization: Bearer . Do not send the Baseten API key directly. No additional routing headers are required. Fetch GET {url}/swagger/doc.json with that header for the API reference served by this sandbox. For example, POST {url}/process with Content-Type: application/json and {"command":"echo hello","waitForCompletion":true} executes a command and waits for its result. Execution API fields use camelCase, independently of this API's snake_case fields. format: uri readOnly: true example: https://sbx-baseten-api-review-0916-esb1qo.us-pdx-1.b10.run status: description: Sandbox deployment status. allOf: - $ref: '#/components/schemas/SandboxStatusV1' example: DEPLOYED created_at: type: string description: Time the sandbox was created. format: date-time readOnly: true example: '2026-09-16T21:26:58.545765901Z' updated_at: type: string description: Time the sandbox was last updated. format: date-time readOnly: true example: '2026-09-16T21:31:13Z' created_by: type: string description: User or service account that created the sandbox. readOnly: true example: sandbox-automation updated_by: type: string description: User or service account that last updated the sandbox. readOnly: true example: sandbox-automation last_used_at: type: string description: Time the sandbox was last used. format: date-time readOnly: true example: '2026-09-16T21:31:13Z' expires_in: type: integer description: >- Seconds remaining before automatic deletion, when expiration is configured. readOnly: true minimum: 0 example: 86400 required: - name - url - status - created_at example: name: baseten-api-review-0916 url: https://sbx-baseten-api-review-0916-esb1qo.us-pdx-1.b10.run status: DEPLOYED created_at: '2026-09-16T21:26:58.545765901Z' updated_at: '2026-09-16T21:31:13Z' created_by: sandbox-automation updated_by: sandbox-automation last_used_at: '2026-09-16T21:31:13Z' expires_in: 86400 example: lifecycle: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h network: proxy: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 subnet: default region: us-pdx-1 envs: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' image: baseten/base-image:latest memory: 4096 ports: - name: http protocol: HTTP target: 3000 external_id: api-review-20260916-001 labels: env: development project: api-review team: engineering name: baseten-api-review-0916 url: https://sbx-baseten-api-review-0916-esb1qo.us-pdx-1.b10.run status: DEPLOYED created_at: '2026-09-16T21:26:58.545765901Z' updated_at: '2026-09-16T21:31:13Z' created_by: sandbox-automation updated_by: sandbox-automation last_used_at: '2026-09-16T21:31:13Z' expires_in: 86400 SandboxLifecycleV1: type: object description: >- Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates properties: expiration_policies: type: array description: >- List of expiration policies. Multiple policies can be combined; whichever condition is met first triggers the action. items: $ref: '#/components/schemas/SandboxExpirationPolicyV1' example: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: allOf: - $ref: '#/components/schemas/SandboxDurationV1' description: >- Duration to keep the sandbox record after termination for log access (e.g., '1h', '24h', '7d'). Defaults to 5m. Subject to maximum quota limits. example: 24h example: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h SandboxEnvV1: type: object description: Environment variable with name and value properties: name: type: string description: Name of the environment variable example: NODE_ENV secret: type: boolean description: >- Whether the value is a secret. Defaults to true; secret values are returned as "****". Set false explicitly to return the original value. default: true example: false value: type: string description: Value of the environment variable example: production example: name: NODE_ENV secret: false value: production SandboxMetadataLabelsV1: type: object description: >- Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy. additionalProperties: type: string example: env: development project: api-review team: engineering SandboxConfigurationV1: type: object description: >- Writable sandbox configuration. Fields are serialized at the root of the request or resource. properties: lifecycle: description: >- Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates allOf: - $ref: '#/components/schemas/SandboxLifecycleV1' example: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h network: description: >- Network configuration for a sandbox including subnet, domain filtering, and proxy settings allOf: - $ref: '#/components/schemas/SandboxNetworkV1' example: proxy: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key subnet: default region: type: string description: >- Region where the sandbox runs (for example us-pdx-1 or eu-lon-1). When omitted at creation, the closest region is selected. example: us-pdx-1 envs: type: array description: Environment variables injected into the sandbox. items: $ref: '#/components/schemas/SandboxEnvV1' example: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' image: type: string description: >- Image reference including its tag. Built-in image references are returned in the canonical baseten/ namespace. Use baseten/base-image:latest to get started with the built-in sandbox execution API. This image is available directly without building, pushing, or listing images through GET /v1/sandboxes/images. example: baseten/base-image:latest memory: type: integer description: >- Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs). example: 4096 minimum: 1 ports: description: Set of ports for a resource allOf: - $ref: '#/components/schemas/SandboxPortsV1' example: - name: http protocol: HTTP target: 3000 external_id: type: string description: >- Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash. example: api-review-20260916-001 maxLength: 64 pattern: ^[A-Za-z0-9-]+$ labels: description: >- Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy. allOf: - $ref: '#/components/schemas/SandboxMetadataLabelsV1' example: env: development project: api-review team: engineering example: lifecycle: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h network: proxy: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key subnet: default region: us-pdx-1 envs: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' image: baseten/base-image:latest memory: 4096 ports: - name: http protocol: HTTP target: 3000 external_id: api-review-20260916-001 labels: env: development project: api-review team: engineering SandboxStatusV1: type: string description: >- Sandbox deployment status, always uppercase. This tracks provisioning and differs from the execution API state, whose values such as running are lowercase. enum: - DEPLOYING - DEPLOYED - FAILED - DEACTIVATING - DEACTIVATED - DELETING - TERMINATED - ARCHIVING - ARCHIVED - UNARCHIVING - BUILDING - UPLOADING readOnly: true example: DEPLOYED SandboxExpirationPolicyV1: description: >- Expiration policy. The type determines whether value is a duration or an absolute timestamp. oneOf: - $ref: '#/components/schemas/SandboxTTLIdleExpirationPolicyV1' - $ref: '#/components/schemas/SandboxTTLMaxAgeExpirationPolicyV1' - $ref: '#/components/schemas/SandboxDateExpirationPolicyV1' discriminator: propertyName: type mapping: TTL_IDLE: '#/components/schemas/SandboxTTLIdleExpirationPolicyV1' TTL_MAX_AGE: '#/components/schemas/SandboxTTLMaxAgeExpirationPolicyV1' DATE: '#/components/schemas/SandboxDateExpirationPolicyV1' SandboxDurationV1: type: string description: >- Duration using seconds, minutes, hours, or composite durations such as 1h30m. Whole days and weeks are also supported, for example 7d or 2w, where d is 24h and w is 7 × 24h. Days and weeks cannot be combined with other units, so 1d12h is rejected; use 36h instead. Values are returned exactly as sent, without normalization. pattern: >- ^[+-]?(0|[0-9]+[dw]|([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h)(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))*)$ example: 24h SandboxNetworkV1: type: object description: >- Network configuration for a sandbox including subnet, domain filtering, and proxy settings properties: proxy: description: >- Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection allOf: - $ref: '#/components/schemas/SandboxProxyConfigV1' example: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key subnet: type: string description: Subnet name for the sandbox. Defaults to "default" at creation. example: default example: proxy: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key subnet: default SandboxPortsV1: type: array description: Set of ports for a resource items: $ref: '#/components/schemas/SandboxPortV1' example: - name: http protocol: HTTP target: 3000 SandboxTTLIdleExpirationPolicyV1: type: object description: Delete after the specified period of inactivity. required: - action - type - value properties: action: type: string enum: - DELETE type: type: string enum: - TTL_IDLE value: $ref: '#/components/schemas/SandboxDurationV1' SandboxTTLMaxAgeExpirationPolicyV1: type: object description: Delete after the specified total lifetime. required: - action - type - value properties: action: type: string enum: - DELETE type: type: string enum: - TTL_MAX_AGE value: $ref: '#/components/schemas/SandboxDurationV1' SandboxDateExpirationPolicyV1: type: object description: Delete at the specified absolute timestamp. required: - action - type - value properties: action: type: string enum: - DELETE type: type: string enum: - DATE value: type: string format: date-time example: '2026-09-23T21:26:58Z' SandboxProxyConfigV1: type: object description: >- Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection properties: allowed_domains: type: array description: >- List of allowed external domains (allowlist). When set, only these domains are reachable. Supports wildcards (e.g. *.storage.example.com). items: type: string example: api.openai.com example: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: type: array description: >- Domains that bypass the proxy entirely via the NO_PROXY directive. Traffic to these destinations goes direct, not through the CONNECT tunnel. Supports wildcards. Note that localhost, private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), 169.254.169.254, .local and .internal are always bypassed by default. items: type: string example: registry.npmjs.org example: - registry.npmjs.org forbidden_domains: type: array description: >- List of forbidden external domains (denylist). When set, all domains except these are reachable. Supports wildcards (e.g. *.malware.com). If both allowed_domains and forbidden_domains are set, allowed_domains takes precedence. items: type: string example: facebook.com example: - facebook.com - '*.facebook.com' routing: type: array description: >- Per-destination routing rules with header/body injection and secrets. Use destinations ["*"] for global rules that apply to all destinations. items: $ref: '#/components/schemas/SandboxProxyTargetV1' example: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key example: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key SandboxPortV1: type: object description: A port for a resource properties: name: type: string description: The name of the port example: http protocol: type: string description: The protocol of the port enum: - HTTP - TCP - UDP - TLS example: HTTP target: type: integer description: The target port of the port example: 3000 minimum: 1 maximum: 65535 required: - target example: name: http protocol: HTTP target: 3000 SandboxProxyTargetV1: type: object description: >- Routing rule that injects headers and body fields into requests matching the given destinations. Use destinations ["*"] for a global rule that applies to all proxied traffic. properties: body: type: object description: >- Body fields to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets. additionalProperties: type: string example: user: baseten-api-review-0916 destinations: type: array description: >- Destination domains this rule applies to. Use ["*"] for a global rule that matches all destinations. items: type: string example: api.openai.com example: - api.openai.com headers: type: object description: >- Headers to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets. additionalProperties: type: string example: Authorization: Bearer {{SECRET:openai-key}} secrets: type: object description: >- Named secret values for this routing rule, referenced in headers/body via {{SECRET:name}}. Stored encrypted at rest. Write-only: never returned in API responses. additionalProperties: type: string example: openai-key: sk-proj-demo-not-a-valid-api-key writeOnly: true example: destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 secrets: openai-key: sk-proj-demo-not-a-valid-api-key examples: UpdateSandbox: summary: Update every mutable field value: lifecycle: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h envs: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' external_id: api-review-20260916-001 labels: env: development project: api-review team: engineering revision: '2' description: >- All mutable request fields are shown. Memory and network configuration are only accepted during creation. SandboxUpdated: summary: Updated sandbox with complete configuration value: lifecycle: expiration_policies: - action: DELETE type: TTL_IDLE value: 24h - action: DELETE type: TTL_MAX_AGE value: 7d - action: DELETE type: DATE value: '2026-09-23T21:26:58Z' terminated_retention: 24h network: proxy: allowed_domains: - api.openai.com - pypi.org - files.pythonhosted.org - registry.npmjs.org bypass: - registry.npmjs.org forbidden_domains: - facebook.com - '*.facebook.com' routing: - destinations: - api.openai.com headers: Authorization: Bearer {{SECRET:openai-key}} body: user: baseten-api-review-0916 subnet: default region: us-pdx-1 envs: - name: NODE_ENV secret: false value: production - name: PORT secret: false value: '3000' image: baseten/base-image:latest memory: 4096 ports: - name: http protocol: HTTP target: 3000 external_id: api-review-20260916-001 labels: env: development project: api-review team: engineering revision: '2' name: baseten-api-review-0916 url: https://sbx-baseten-api-review-0916-esb1qo.us-pdx-1.b10.run status: DEPLOYED created_at: '2026-09-16T21:26:58.545765901Z' updated_at: '2026-09-16T21:36:13Z' created_by: sandbox-automation updated_by: sandbox-automation last_used_at: '2026-09-16T21:36:13Z' expires_in: 86400 responses: SandboxError401: description: >- Missing or invalid authentication. Returns a JSON error with code, message, and optional details. content: application/json: example: code: UNAUTHORIZED message: Provide a valid authentication token in the Authorization header. details: header: Authorization SandboxError403: description: >- Insufficient permissions. Returns a JSON error with code, message, and optional details. content: application/json: example: code: FORBIDDEN message: >- This authentication token does not grant permission to perform this operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError404: description: >- Resource not found. Returns a JSON error with code, message, and optional details. content: application/json: example: code: NOT_FOUND message: The requested resource was not found. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError409: description: >- Resource is currently in use or conflicts with the requested operation. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RESOURCE_IN_USE message: >- The resource is currently in use or conflicts with the requested operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError429: description: >- Request limit exceeded. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RATE_LIMITED message: Too many requests. Try again in 30 seconds. details: retry_after_seconds: 30 SandboxError500: description: >- Internal server error. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INTERNAL_ERROR message: The request could not be completed. Try again later. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send `Authorization: Bearer `. The legacy `Authorization: Api-Key ` scheme is also accepted. ````