---
title: "Create sandbox"
method: POST
path: "/sandboxes"
tags: ["compute"]
---

# Create sandbox

`POST /sandboxes`

Creates a new sandbox VM for secure AI code execution. Sandboxes automatically scale to zero when idle and resume instantly, preserving memory state including running processes and filesystem.

## Query parameters

- `createIfNotExist` boolean

## Request body

- Sandbox — 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.
  - `events` CoreEvent[] — Events happening on a resource deployed on Blaxel
    - `canaryRevision` string — Canary revisionID link to the event
    - `message` string — Event message
    - `revision` string — RevisionID link to the event
    - `status` string — Event status
    - `time` string — Event time
    - `type` string — Event type
  - `expiresIn` integer — Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured.
  - `lastUsedAt` string — Last time the sandbox was used (read-only, managed by the system)
  - `metadata` Metadata, required — Owner fields for Persistence
    - `createdAt` string — The date and time when the resource was created
    - `updatedAt` string — The date and time when the resource was updated
    - `createdBy` string — The user or service account who created the resource
    - `updatedBy` string — The user or service account who updated the resource
    - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
    - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
    - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
    - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
    - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
    - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
  - `nodeGeneration` string — Infrastructure generation this sandbox is deployed on (mk3.0 or mk3.1). Read-only.
  - `spec` SandboxSpec, required — Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies
    - `enabled` boolean — When false, the sandbox is disabled and will not accept connections
    - `lifecycle` SandboxLifecycle — Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates
      - `expirationPolicies` ExpirationPolicy[] — List of expiration policies. Multiple policies can be combined; whichever condition is met first triggers the action.
        - `action` 'delete' — Action to take when the expiration condition is met
        - `type` 'ttl-idle' | 'ttl-max-age' | 'date' — Type of expiration policy: ttl-idle (delete after inactivity), ttl-max-age (delete after total lifetime), or date (delete at specific time)
        - `value` string — Duration value for TTL policies (e.g., '30m', '24h', '7d') or ISO 8601 date for date policies
      - `terminatedRetention` string — Duration to keep the sandbox record after termination for log access (e.g., '1h', '24h', '7d'). Defaults to 5m. Subject to maximum quota limits.
    - `network` SandboxNetwork — Network configuration for a sandbox including subnet, firewall rulesets, domain filtering, egress IP binding, and proxy settings
      - `allowedDomains` string[] — Deprecated: use proxy.allowedDomains instead. List of allowed external domains (allowlist). Kept for backward compatibility.
      - `egress` EgressConfig — Egress configuration for routing sandbox outbound traffic through a dedicated IP gateway
        - `gateway` string — Name of the egress gateway to route traffic through. The gateway must exist in the default VPC.
        - `mode` string — Egress mode. Use 'dedicated' for a dedicated egress IP.
        - `policies` EgressPolicy[] — Per-destination egress policies (not yet supported)
          - `destinations` string[] — Destination domains or IPs this policy applies to
          - `mode` string — Egress mode for these destinations (dedicated or shared)
          - `name` string — Name of this egress policy
      - `firewall` FirewallConfig — Firewall configuration specifying which network lockdown rulesets to apply. Valid rulesets are "default" (no-op), "proxy" (restrict egress to proxy), and "dedicated-ip" (restrict egress to dedicated IP gateway).
        - `rulesets` string[] — List of firewall rulesets to apply. Valid values: "default" (no-op), "proxy" (restrict egress to proxy), "dedicated-ip" (restrict egress to dedicated IP gateway).
      - `forbiddenDomains` string[] — Deprecated: use proxy.forbiddenDomains instead. List of forbidden external domains (denylist). Kept for backward compatibility.
      - `proxy` ProxyConfig — Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection
        - `allowedDomains` string[] — List of allowed external domains (allowlist). When set, only these domains are reachable. Supports wildcards (e.g. *.s3.amazonaws.com).
        - `bypass` string[] — 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.
        - `forbiddenDomains` string[] — 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.
        - `routing` ProxyTarget[] — Per-destination routing rules with header/body injection and secrets. Use destinations ["*"] for global rules that apply to all destinations.
          - `body` object — Body fields to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets.
          - `destinations` string[] — Destination domains this rule applies to. Use ["*"] for a global rule that matches all destinations.
          - `headers` object — Headers to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets.
          - `secrets` object — 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.
      - `subnet` string — Subnet name for the sandbox. Takes priority over any subnet derived from egress config. Defaults to "default" when absent.
    - `region` string — 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.
    - `runtime` SandboxRuntime — Runtime configuration defining how the sandbox VM is provisioned and its resource limits
      - `envs` Env[] — Environment variables injected into the sandbox. Supports Kubernetes EnvVar format with valueFrom references.
        - `name` string — Name of the environment variable
        - `secret` boolean — Whether the value is a secret
        - `value` string — Value of the environment variable
      - `expires` string — Absolute expiration timestamp in ISO 8601 format when the sandbox will be deleted
      - `extraArgs` object — Extra arguments for kernel selection. Supported keys: 'iptables', 'nfs' (mk3.0), 'tun' (mk3.1). Values: 'enabled' or 'disabled'. Determines which kernel variant the workload runs on. Immutable after creation.
      - `image` string — 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'.
      - `memory` integer — Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
      - `ports` Port[] — Set of ports for a resource
        - `name` string — The name of the port
        - `protocol` 'HTTP' | 'TCP' | 'UDP' | 'TLS' — The protocol of the port
        - `target` integer, required — The target port of the port
      - `terminationGracePeriodSeconds` integer — Duration in seconds the pod needs to terminate gracefully. Defaults to 0 for immediate termination.
      - `ttl` string — Max-age from creation: the sandbox is deleted this long after it is created, regardless of activity (not an idle timeout). Units s, m, h, d, w (e.g., '30m', '24h', '7d', '2w'). For idle-based cleanup, use a lifecycle expiration policy of type ttl-idle.
    - `volumes` VolumeAttachment[]
      - `mountPath` string — Absolute filesystem path where the volume will be mounted inside the sandbox
      - `name` string — Name of the volume resource to attach (must exist in the same workspace and region)
      - `readOnly` boolean — If true, the volume is mounted read-only and cannot be modified by the sandbox
    - `vpc` string — VPC name for the sandbox. Defaults to "default" when absent.
  - `state` 'RUNNING' | 'STANDBY' — Current state of the sandbox (read-only, managed by the system)
  - `status` 'DELETING' | 'TERMINATED' | 'FAILED' | 'DEACTIVATED' | 'DEACTIVATING' | 'UPLOADING' | 'BUILDING' | 'DEPLOYING' | 'DEPLOYED' | 'BUILT' — Deployment status of a resource deployed on Blaxel

## Response `200`

successful operation

- Sandbox — 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.
  - `events` CoreEvent[] — Events happening on a resource deployed on Blaxel
    - `canaryRevision` string — Canary revisionID link to the event
    - `message` string — Event message
    - `revision` string — RevisionID link to the event
    - `status` string — Event status
    - `time` string — Event time
    - `type` string — Event type
  - `expiresIn` integer — Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured.
  - `lastUsedAt` string — Last time the sandbox was used (read-only, managed by the system)
  - `metadata` Metadata, required — Owner fields for Persistence
    - `createdAt` string — The date and time when the resource was created
    - `updatedAt` string — The date and time when the resource was updated
    - `createdBy` string — The user or service account who created the resource
    - `updatedBy` string — The user or service account who updated the resource
    - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
    - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
    - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
    - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
    - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
    - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
  - `nodeGeneration` string — Infrastructure generation this sandbox is deployed on (mk3.0 or mk3.1). Read-only.
  - `spec` SandboxSpec, required — Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies
    - `enabled` boolean — When false, the sandbox is disabled and will not accept connections
    - `lifecycle` SandboxLifecycle — Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates
      - `expirationPolicies` ExpirationPolicy[] — List of expiration policies. Multiple policies can be combined; whichever condition is met first triggers the action.
        - `action` 'delete' — Action to take when the expiration condition is met
        - `type` 'ttl-idle' | 'ttl-max-age' | 'date' — Type of expiration policy: ttl-idle (delete after inactivity), ttl-max-age (delete after total lifetime), or date (delete at specific time)
        - `value` string — Duration value for TTL policies (e.g., '30m', '24h', '7d') or ISO 8601 date for date policies
      - `terminatedRetention` string — Duration to keep the sandbox record after termination for log access (e.g., '1h', '24h', '7d'). Defaults to 5m. Subject to maximum quota limits.
    - `network` SandboxNetwork — Network configuration for a sandbox including subnet, firewall rulesets, domain filtering, egress IP binding, and proxy settings
      - `allowedDomains` string[] — Deprecated: use proxy.allowedDomains instead. List of allowed external domains (allowlist). Kept for backward compatibility.
      - `egress` EgressConfig — Egress configuration for routing sandbox outbound traffic through a dedicated IP gateway
        - `gateway` string — Name of the egress gateway to route traffic through. The gateway must exist in the default VPC.
        - `mode` string — Egress mode. Use 'dedicated' for a dedicated egress IP.
        - `policies` EgressPolicy[] — Per-destination egress policies (not yet supported)
          - `destinations` string[] — Destination domains or IPs this policy applies to
          - `mode` string — Egress mode for these destinations (dedicated or shared)
          - `name` string — Name of this egress policy
      - `firewall` FirewallConfig — Firewall configuration specifying which network lockdown rulesets to apply. Valid rulesets are "default" (no-op), "proxy" (restrict egress to proxy), and "dedicated-ip" (restrict egress to dedicated IP gateway).
        - `rulesets` string[] — List of firewall rulesets to apply. Valid values: "default" (no-op), "proxy" (restrict egress to proxy), "dedicated-ip" (restrict egress to dedicated IP gateway).
      - `forbiddenDomains` string[] — Deprecated: use proxy.forbiddenDomains instead. List of forbidden external domains (denylist). Kept for backward compatibility.
      - `proxy` ProxyConfig — Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection
        - `allowedDomains` string[] — List of allowed external domains (allowlist). When set, only these domains are reachable. Supports wildcards (e.g. *.s3.amazonaws.com).
        - `bypass` string[] — 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.
        - `forbiddenDomains` string[] — 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.
        - `routing` ProxyTarget[] — Per-destination routing rules with header/body injection and secrets. Use destinations ["*"] for global rules that apply to all destinations.
          - `body` object — Body fields to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets.
          - `destinations` string[] — Destination domains this rule applies to. Use ["*"] for a global rule that matches all destinations.
          - `headers` object — Headers to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets.
          - `secrets` object — 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.
      - `subnet` string — Subnet name for the sandbox. Takes priority over any subnet derived from egress config. Defaults to "default" when absent.
    - `region` string — 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.
    - `runtime` SandboxRuntime — Runtime configuration defining how the sandbox VM is provisioned and its resource limits
      - `envs` Env[] — Environment variables injected into the sandbox. Supports Kubernetes EnvVar format with valueFrom references.
        - `name` string — Name of the environment variable
        - `secret` boolean — Whether the value is a secret
        - `value` string — Value of the environment variable
      - `expires` string — Absolute expiration timestamp in ISO 8601 format when the sandbox will be deleted
      - `extraArgs` object — Extra arguments for kernel selection. Supported keys: 'iptables', 'nfs' (mk3.0), 'tun' (mk3.1). Values: 'enabled' or 'disabled'. Determines which kernel variant the workload runs on. Immutable after creation.
      - `image` string — 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'.
      - `memory` integer — Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
      - `ports` Port[] — Set of ports for a resource
        - `name` string — The name of the port
        - `protocol` 'HTTP' | 'TCP' | 'UDP' | 'TLS' — The protocol of the port
        - `target` integer, required — The target port of the port
      - `terminationGracePeriodSeconds` integer — Duration in seconds the pod needs to terminate gracefully. Defaults to 0 for immediate termination.
      - `ttl` string — Max-age from creation: the sandbox is deleted this long after it is created, regardless of activity (not an idle timeout). Units s, m, h, d, w (e.g., '30m', '24h', '7d', '2w'). For idle-based cleanup, use a lifecycle expiration policy of type ttl-idle.
    - `volumes` VolumeAttachment[]
      - `mountPath` string — Absolute filesystem path where the volume will be mounted inside the sandbox
      - `name` string — Name of the volume resource to attach (must exist in the same workspace and region)
      - `readOnly` boolean — If true, the volume is mounted read-only and cannot be modified by the sandbox
    - `vpc` string — VPC name for the sandbox. Defaults to "default" when absent.
  - `state` 'RUNNING' | 'STANDBY' — Current state of the sandbox (read-only, managed by the system)
  - `status` 'DELETING' | 'TERMINATED' | 'FAILED' | 'DEACTIVATED' | 'DEACTIVATING' | 'UPLOADING' | 'BUILDING' | 'DEPLOYING' | 'DEPLOYED' | 'BUILT' — Deployment status of a resource deployed on Blaxel

## Other responses

- `400` — Bad request - Invalid sandbox configuration (e.g., invalid region, image not found)
- `401` — Unauthorized - Invalid or missing authentication credentials
- `403` — Forbidden - Insufficient permissions to create sandboxes
- `409` — Conflict - Sandbox with this name already exists
- `500` — Internal server error

---

[API](https://skmtc.net/blaxel/apis/blaxel-control-plane.md) · [All operations](https://skmtc.net/blaxel/apis/blaxel-control-plane/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blaxel/blaxel-control-plane/versions/dfa264bc72ee/schema)