> ## Documentation Index > Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update sandbox > Updates a sandbox's configuration. Note that certain changes (like image or memory) may reset the sandbox state. Use lifecycle policies to control automatic cleanup. ## OpenAPI ````yaml /api-reference/controlplane.yml put /sandboxes/{sandboxName} openapi: 3.0.3 info: title: Blaxel Control Plane version: 0.0.1 servers: - description: Blaxel Control Plane url: https://api.blaxel.ai/v0 - description: Blaxel Inference url: https://run.blaxel.ai security: - OAuth2: - admin - ApiKeyAuth: [] paths: /sandboxes/{sandboxName}: parameters: - description: Unique name identifier of the sandbox in: path name: sandboxName required: true schema: type: string put: tags: - compute summary: Update sandbox description: >- Updates a sandbox's configuration. Note that certain changes (like image or memory) may reset the sandbox state. Use lifecycle policies to control automatic cleanup. operationId: UpdateSandbox requestBody: content: application/json: schema: $ref: '#/components/schemas/Sandbox' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Sandbox' description: successful operation '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request - Invalid sandbox configuration '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized - Invalid or missing authentication credentials '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden - Insufficient permissions to update this sandbox '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found - Sandbox does not exist '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal server error security: - OAuth2: - sandboxes:update - ApiKeyAuth: [] components: schemas: Sandbox: type: object description: >- Lightweight virtual machine for secure AI code execution. Sandboxes resume from standby in under 25ms and automatically scale to zero after inactivity, preserving memory state including running processes and filesystem. properties: events: $ref: '#/components/schemas/CoreEvents' expiresIn: type: integer description: >- Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured. readOnly: true lastUsedAt: type: string description: Last time the sandbox was used (read-only, managed by the system) readOnly: true metadata: $ref: '#/components/schemas/Metadata' spec: $ref: '#/components/schemas/SandboxSpec' state: type: string description: Current state of the sandbox (read-only, managed by the system) enum: - RUNNING - STANDBY readOnly: true status: $ref: '#/components/schemas/Status' required: - metadata - spec Error: type: object description: Standard error response returned by the API when a request fails properties: code: type: integer description: HTTP status code of the error example: 409 error: type: string description: Error type or code identifying the kind of error example: Resource already exists message: type: string description: Human-readable error message describing what went wrong example: Invalid request body required: - error CoreEvents: type: array description: Events happening on a resource deployed on Blaxel items: $ref: '#/components/schemas/CoreEvent' readOnly: true Metadata: type: object description: >- Common metadata fields shared by all Blaxel resources including name, labels, timestamps, and ownership information allOf: - $ref: '#/components/schemas/TimeFields' - $ref: '#/components/schemas/OwnerFields' - properties: displayName: type: string description: >- Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters. example: My Resource labels: $ref: '#/components/schemas/MetadataLabels' name: type: string description: >- Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation. example: my-resource plan: type: string description: >- Billing plan tier applied to this resource (inherited from workspace account) readOnly: true url: type: string description: >- Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes) readOnly: true workspace: type: string description: >- Name of the workspace this resource belongs to (read-only, set automatically) readOnly: true required: - name SandboxSpec: type: object description: >- Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies properties: enabled: type: boolean description: When false, the sandbox is disabled and will not accept connections example: true default: true lifecycle: $ref: '#/components/schemas/SandboxLifecycle' network: $ref: '#/components/schemas/SandboxNetwork' region: type: string description: >- Region where the sandbox should be created (e.g. us-pdx-1, eu-lon-1). If not specified, defaults to the region closest to the user. example: us-pdx-1 runtime: $ref: '#/components/schemas/SandboxRuntime' volumes: $ref: '#/components/schemas/VolumeAttachments' Status: type: string description: Deployment status of a resource deployed on Blaxel enum: - DELETING - TERMINATED - FAILED - DEACTIVATED - DEACTIVATING - UPLOADING - BUILDING - DEPLOYING - DEPLOYED - BUILT readOnly: true CoreEvent: type: object description: Core event properties: canaryRevision: type: string description: Canary revisionID link to the event message: type: string description: Event message example: Deployment successful revision: type: string description: RevisionID link to the event example: rev-abc123 status: type: string description: Event status example: DEPLOYED time: type: string description: Event time example: '2025-01-15T10:30:00Z' type: type: string description: Event type example: deployment readOnly: true TimeFields: type: object description: Time fields for Persistance properties: createdAt: type: string description: The date and time when the resource was created readOnly: true updatedAt: type: string description: The date and time when the resource was updated readOnly: true OwnerFields: type: object description: Owner fields for Persistance properties: createdBy: type: string description: The user or service account who created the resource readOnly: true updatedBy: type: string description: The user or service account who updated the resource readOnly: true MetadataLabels: 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 SandboxLifecycle: type: object description: >- Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates properties: expirationPolicies: type: array description: >- List of expiration policies. Multiple policies can be combined; whichever condition is met first triggers the action. items: $ref: '#/components/schemas/ExpirationPolicy' terminatedRetention: type: string 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 SandboxNetwork: type: object description: >- Network configuration for a sandbox including domain filtering, egress IP binding, and proxy settings properties: allowedDomains: type: array description: >- List of allowed external domains (allowlist). When set, only these domains are reachable. Supports wildcards (e.g. *.s3.amazonaws.com). items: type: string example: '["api.stripe.com", "api.openai.com", "*.s3.amazonaws.com"]' egress: $ref: '#/components/schemas/EgressConfig' forbiddenDomains: 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 allowedDomains and forbiddenDomains are set, allowedDomains takes precedence. items: type: string example: '["*.malware.com", "evil.example.org"]' proxy: $ref: '#/components/schemas/ProxyConfig' SandboxRuntime: type: object description: >- Runtime configuration defining how the sandbox VM is provisioned and its resource limits properties: envs: type: array description: >- Environment variables injected into the sandbox. Supports Kubernetes EnvVar format with valueFrom references. items: $ref: '#/components/schemas/Env' expires: type: string description: >- Absolute expiration timestamp in ISO 8601 format when the sandbox will be deleted example: '2025-12-31T23:59:59Z' extraArgs: type: object description: >- Extra arguments for sandbox kernel selection. Supported keys: 'iptables', 'nvme'. Values: 'enabled' or 'disabled'. Determines which kernel variant the sandbox runs on. Immutable after creation. additionalProperties: type: string image: type: string description: >- Sandbox image to use. Can be a public Blaxel image (e.g., blaxel/base-image:latest) or a custom template image built with 'bl deploy'. example: blaxel/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 ports: $ref: '#/components/schemas/Ports' terminationGracePeriodSeconds: type: integer description: >- Duration in seconds the pod needs to terminate gracefully. Defaults to 0 for immediate termination. example: 30 ttl: type: string description: >- Time-to-live duration after which the sandbox is automatically deleted (e.g., '30m', '24h', '7d') example: 24h VolumeAttachments: type: array items: $ref: '#/components/schemas/VolumeAttachment' ExpirationPolicy: type: object description: Expiration policy for automatic sandbox cleanup based on time conditions properties: action: type: string description: Action to take when the expiration condition is met enum: - delete example: delete type: type: string description: >- Type of expiration policy: ttl-idle (delete after inactivity), ttl-max-age (delete after total lifetime), or date (delete at specific time) enum: - ttl-idle - ttl-max-age - date example: ttl-idle value: type: string description: >- Duration value for TTL policies (e.g., '30m', '24h', '7d') or ISO 8601 date for date policies example: 24h EgressConfig: type: object description: >- Egress configuration for routing sandbox outbound traffic through a dedicated IP gateway properties: gateway: type: string description: >- Name of the egress gateway to route traffic through. The gateway must exist in the default VPC. example: egress-ip-gw-1 mode: type: string description: Egress mode. Use 'dedicated' for a dedicated egress IP. example: dedicated policies: type: array description: Per-destination egress policies (not yet supported) items: $ref: '#/components/schemas/EgressPolicy' ProxyConfig: type: object description: >- Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection properties: 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: '["*.s3.amazonaws.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/ProxyTarget' Env: type: object description: Environment variable with name and value properties: name: type: string description: Name of the environment variable example: MY_ENV_VAR secret: type: boolean description: Whether the value is a secret example: true value: type: string description: Value of the environment variable example: my-value Ports: type: array description: Set of ports for a resource items: $ref: '#/components/schemas/Port' VolumeAttachment: type: object description: >- Configuration for attaching a persistent volume to a sandbox at a specific filesystem path properties: mountPath: type: string description: >- Absolute filesystem path where the volume will be mounted inside the sandbox example: /mnt/data name: type: string description: >- Name of the volume resource to attach (must exist in the same workspace and region) example: my-volume readOnly: type: boolean description: >- If true, the volume is mounted read-only and cannot be modified by the sandbox example: false EgressPolicy: type: object description: >- Egress policy routing specific destinations through dedicated or shared gateways (not yet supported) properties: destinations: type: array description: Destination domains or IPs this policy applies to items: type: string example: '["api.stripe.com"]' mode: type: string description: Egress mode for these destinations (dedicated or shared) example: dedicated name: type: string description: Name of this egress policy example: payment-apis ProxyTarget: 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: '{"api_key": "{{SECRET:stripe-key}}"}' destinations: type: array description: >- Destination domains this rule applies to. Use ["*"] for a global rule that matches all destinations. items: type: string example: '["api.stripe.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:stripe-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: '{"stripe-key": "sk-live-abc123..."}' Port: 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: 8080 required: - target securitySchemes: OAuth2: description: OAuth2 authentication with JWT tokens flows: authorizationCode: authorizationUrl: /oauth/authorize scopes: admin: Administrative access agents:create: Create agents agents:delete: Delete agents agents:get: Get agent details agents:list: List agents agents:update: Update agents apiKey:list: List API keys apiKey:write: Create and delete API keys configurations:list: List configurations customdomains:create: Create custom domains customdomains:delete: Delete custom domains customdomains:get: Get custom domain details customdomains:list: List custom domains customdomains:update: Update custom domains functions:create: Create functions functions:delete: Delete functions functions:get: Get function details functions:list: List functions functions:update: Update functions integrations:create: Create integrations integrations:list: List integrations invitations:list: List invitations jobs:create: Create jobs jobs:delete: Delete jobs jobs:get: Get job details jobs:list: List jobs jobs:update: Update jobs locations:list: List locations mcphub:list: List MCP hub resources models:create: Create models models:delete: Delete models models:get: Get model details models:list: List models models:update: Update models policies:create: Create policies policies:delete: Delete policies policies:get: Get policy details policies:list: List policies policies:update: Update policies sandboxes:control: Control sandbox operations sandboxes:create: Create sandboxes sandboxes:delete: Delete sandboxes sandboxes:get: Get sandbox details sandboxes:list: List sandboxes sandboxes:update: Update sandboxes sandboxhub:list: List sandbox hub resources templates:get: Get template details templates:list: List templates volumeTemplates:create: Create volume templates volumeTemplates:delete: Delete volume templates volumeTemplates:get: Get volume template details volumeTemplates:list: List volume templates volumeTemplates:upsert: Create or update volume templates volumes:create: Create volumes volumes:delete: Delete volumes volumes:get: Get volume details volumes:list: List volumes workspaces:accept: Accept workspace invitation workspaces:create: Create workspaces workspaces:decline: Decline workspace invitation workspaces:delete: Delete workspaces workspaces:get: Get workspace details workspaces:invite: Invite users to workspace workspaces:leave: Leave workspace workspaces:list: List workspaces workspaces:remove: Remove users from workspace workspaces:update: Update workspaces tokenUrl: /oauth/token clientCredentials: scopes: admin: Administrative access agents:create: Create agents agents:delete: Delete agents agents:get: Get agent details agents:list: List agents agents:update: Update agents apiKey:list: List API keys apiKey:write: Create and delete API keys configurations:list: List configurations customdomains:create: Create custom domains customdomains:delete: Delete custom domains customdomains:get: Get custom domain details customdomains:list: List custom domains customdomains:update: Update custom domains functions:create: Create functions functions:delete: Delete functions functions:get: Get function details functions:list: List functions functions:update: Update functions integrations:create: Create integrations integrations:list: List integrations invitations:list: List invitations jobs:create: Create jobs jobs:delete: Delete jobs jobs:get: Get job details jobs:list: List jobs jobs:update: Update jobs locations:list: List locations mcphub:list: List MCP hub resources models:create: Create models models:delete: Delete models models:get: Get model details models:list: List models models:update: Update models policies:create: Create policies policies:delete: Delete policies policies:get: Get policy details policies:list: List policies policies:update: Update policies sandboxes:control: Control sandbox operations sandboxes:create: Create sandboxes sandboxes:delete: Delete sandboxes sandboxes:get: Get sandbox details sandboxes:list: List sandboxes sandboxes:update: Update sandboxes sandboxhub:list: List sandbox hub resources templates:get: Get template details templates:list: List templates volumeTemplates:create: Create volume templates volumeTemplates:delete: Delete volume templates volumeTemplates:get: Get volume template details volumeTemplates:list: List volume templates volumeTemplates:upsert: Create or update volume templates volumes:create: Create volumes volumes:delete: Delete volumes volumes:get: Get volume details volumes:list: List volumes workspaces:accept: Accept workspace invitation workspaces:create: Create workspaces workspaces:decline: Decline workspace invitation workspaces:delete: Delete workspaces workspaces:get: Get workspace details workspaces:invite: Invite users to workspace workspaces:leave: Leave workspace workspaces:list: List workspaces workspaces:remove: Remove users from workspace workspaces:update: Update workspaces tokenUrl: /oauth/token type: oauth2 ApiKeyAuth: bearerFormat: API Key description: Long-lived API key for programmatic access scheme: bearer type: http ````