Sandboxes

​

Create a sandbox

import { SandboxInstance } from "@blaxel/core";

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",   // public or custom image
  memory: 4096,   // in MB
  ports: [{ target: 3000, protocol: "HTTP" }],   // optional; ports to expose
  labels: { env: "dev", project: "my-project" }, // optional; labels
  region: "us-pdx-1"   // optional; if not specified, Blaxel will choose a default region
});

import { SandboxInstance } from "@blaxel/core";

// Create sandbox if it doesn't exist
const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",  // public or custom image
  memory: 4096,    // in MB
  ports: [{ target: 3000, protocol: "HTTP" }],  // optional; ports to expose
  labels: { env: "dev", project: "my-project" }, // optional; labels
  region: "us-pdx-1"    // optional; if not specified, Blaxel will choose a default region
});

​

Images

​

Memory and filesystem

​

Ports

• 443: This port hosts the main sandbox API and is exposed via HTTPS
• 80: Reserved for system operations
• 8080: Reserved for sandbox API functionality

​

Regions

​

Expiration date

• expire at a specific date using the expires parameter.
• expire after a total maximum lifetime using the ttl parameter
• expire after a period of inactivity using the lifecycle.expirationPolicies / lifecycle.expiration_policies parameter

import { SandboxInstance } from "@blaxel/core";

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
  region: "us-pdx-1",
  ttl: "24h", // Total duration before auto-deletion. Supported units: h, d, w
  // OR
  // expires: new Date(Date.now() + 86400000) // Alternative: set a date at which it will be deleted
  // OR / AND
  lifecycle: {
    expirationPolicies: [
      {
        type: "ttl-idle",
        value: "24h",  // Delete after 24 hours of inactivity. Supported units: h, d, w
        action: "delete"
      }
    ]
  }
});

​

Retrieve an existing sandbox

import { SandboxInstance } from "@blaxel/core";

// Connect to existing sandbox
const sandbox = await SandboxInstance.get("my-sandbox");

​

Delete a sandbox

• the class-level delete() method with the sandbox name as argument, or
  TypeScript

  Python

  Copy

  Ask AI

  import { SandboxInstance } from "@blaxel/core";
  
  // Delete sandbox using class-level method
  await SandboxInstance.delete("my-sandbox");
  
• by calling the instance-level delete() method:
  TypeScript

  Python

  Copy

  Ask AI

  import { SandboxInstance } from "@blaxel/core";
  
  // Get existing sandbox
  const sandbox = await SandboxInstance.get("my-sandbox");
  
  // Delete sandbox using instance-level method
  await sandbox.delete()
  

​

Connect to a sandbox with an interactive terminal

• From the Blaxel Console, by visiting the detail page for your sandbox in your web browser and selecting the Terminal tab:
• From your local host, by running:
  Copy

  Ask AI

  bl connect sandbox your-sandbox-name
  
  

​

Sandbox statuses

• In standby mode: You are not charged for CPU/memory while a sandbox is in standby mode. However, you are charged for the storage of the snapshot and/or the volumes.
• In active mode: You are charged for CPU/memory and storage while a sandbox is in active mode. Sandboxes automatically return to standby mode after 1 second of inactivity.

• UPLOADING: A new sandbox version has just been uploaded; the build has not started yet.
• BUILDING: A new sandbox version has been uploaded and the build is in progress.
• DEPLOYING: The sandbox deployment is in progress.
• DEPLOYED: The sandbox is ready to use.
• FAILED: An error occurred during the build or deployment of the sandbox.
• TERMINATED: A TTL was set for the sandbox; it has been deleted and will be removed from the API/UI soon.
• DELETING: A deletion request has been triggered and the deletion is in progress.

​

Best practices

• If the end-user or agent is expected to continue a session soon, just leave the sandbox be. It will automatically suspend when the connection closes (= you will stop paying for compute runtime) and resume when reconnected.
• The definition of “soon” is at your discretion. It’s a tradeoff between instant resume times from standby mode (~25ms) and paying for the standby snapshot storage cost. As a rule of thumb, most customers keep sandboxes in standby for a few hours to a few days.
• Blaxel doesn’t limit how long a sandbox can stay in standby mode, but doesn’t guarantee data persistence. For guaranteed long-term data persistence, use volumes.
• If you persist data in a volume, you can delete the sandbox. To resume a session, you’ll need to re-create the sandbox (~2–4 seconds) and restart processes to restore the same state.
• For automatic cleanup, set TTLs when creating your sandbox to delete it after a set idle duration or maximum age.
• When you delete a sandbox, all data is immediately erased. If the sandbox was never in standby mode, Blaxel guarantees ZDR (zero data retention).