Sandboxes

​

Sandbox lifecycle

​

Active mode

​

Standby mode

​

Deletion

​

Sandbox deployment statuses

• 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. It is either in active mode or standby mode.
• 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.

​

Use cases

• Code review agents that analyze repositories to detect the effects of changes. These agents run fully isolated compute environments for each tenant while keeping them snapshotted in standby between sessions, eliminating the need to clone the repo every time.
• Code generation agents that iterate in their own compute environments, and instantly render live application previews as human users build, step away, and log back in.
• Data analyst agents that execute adhoc data analysis workflows, generating scripts on-the-fly and running them securely against private files or data within an isolated, ZDR-compliant environment.
• Background agents that operate beyond their pre-configured tools. Each agent gets its own “personal computer” where it can autonomously install packages, execute custom scripts, store files, and adapt to new requirements securely. They can parallelize dozens of those personal computers.

​

Create a sandbox

​

Using the SDKs

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"   // deployment 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"    // deployment region
});

​

Using the CLI and Console

bl new sandbox my-sandbox
cd my-sandbox
bl deploy

​

Using the API

​

Understand sandbox configuration

​

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

​

Labels

// 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
  labels: { env: "dev", project: "my-project" }, // optional; labels
  region: "us-pdx-1"   // deployment region
});

# Get sandboxes with specific label (e.g., env=dev)
bl get sandboxes -o json | jq -r '.[] | select(.metadata.labels.env == "dev") | .metadata.name'

​

Expiration

​

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()
  

​

Upgrade a sandbox’s API

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

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

// Upgrade sandbox API to "latest"
await sandbox.system.upgrade({ version: "latest" })

​

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