compute

Create sandbox

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.

post/sandboxes

Request

Base URL
https://api.blaxel.ai/v0
Auth
- OAuth 2
  Authorization code/oauth/authorize
  Client credentials
  Token URL/oauth/token
  Scopessandboxes:create
- or HTTP bearer
TypeScript
https://skmtc.dev/blaxel/apis/blaxel-control-plane/docs/sandboxes/post.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

createIfNotExistboolean

If true, return existing sandbox instead of 409 error when sandbox exists and is not in FAILED/TERMINATED/TERMINATING state

Request body

expiresIninteger

Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured.

lastUsedAtstring

Last time the sandbox was used (read-only, managed by the system)

nodeGenerationstring

Infrastructure generation this sandbox is deployed on (mk3.0 or mk3.1). Read-only.

state'RUNNING' | 'STANDBY'

Current state of the sandbox (read-only, managed by the system)

Deployment status of a resource deployed on Blaxel

Example request

{
  "events": [
    {
      "message": "Deployment successful",
      "revision": "rev-abc123",
      "status": "DEPLOYED",
      "time": "2025-01-15T10:30:00Z",
      "type": "deployment"
    }
  ],
  "metadata": {
    "displayName": "My Resource",
    "externalId": "my-session-123",
    "name": "my-resource"
  },
  "spec": {
    "enabled": true,
    "lifecycle": {
      "expirationPolicies": [
        {
          "action": "delete",
          "type": "ttl-idle",
          "value": "24h"
        }
      ],
      "terminatedRetention": "24h"
    },
    "network": {
      "egress": {
        "gateway": "egress-ip-gw-1",
        "mode": "dedicated",
        "policies": [
          {
            "mode": "dedicated",
            "name": "payment-apis"
          }
        ]
      },
      "subnet": "default"
    },
    "region": "us-pdx-1",
    "runtime": {
      "envs": [
        {
          "name": "MY_ENV_VAR",
          "secret": true,
          "value": "my-value"
        }
      ],
      "expires": "2025-12-31T23:59:59Z",
      "image": "blaxel/base-image:latest",
      "memory": 4096,
      "ports": [
        {
          "name": "http",
          "protocol": "HTTP",
          "target": 8080
        }
      ],
      "terminationGracePeriodSeconds": 30,
      "ttl": "24h"
    },
    "volumes": [
      {
        "mountPath": "/mnt/data",
        "name": "my-volume"
      }
    ],
    "vpc": "default"
  }
}

Response

successful operation