blaxel-sdk

Blaxel Skill Reference

What is Blaxel

Blaxel (https://blaxel.ai) is a cloud platform that gives AI agents their own compute environments. Its flagship product is perpetual sandboxes: instant-launching microVMs that resume from standby in under 25ms and scale to zero after a few seconds of inactivity.

You use Blaxel primarily to:

• Spin up a sandbox, install dependencies, run a dev server, and expose a live preview URL
• Build and deploy sandbox templates (custom Docker images) for reusable environments
• Deploy AI agents, MCP servers, and batch jobs as serverless endpoints

SDKs: TypeScript (@blaxel/core) and Python (blaxel) CLI: bl (install from https://docs.blaxel.ai/cli-reference/introduction) Docs: https://docs.blaxel.ai

Authentication

The SDK authenticates using these sources in priority order:

1. Blaxel CLI, when logged in
2. Environment variables in .env file (BL_WORKSPACE, BL_API_KEY)
3. System environment variables
4. Blaxel configuration file (~/.blaxel/config.yaml)

Log in locally (recommended for development):

bl login YOUR-WORKSPACE

Or set environment variables (for remote/CI environments):

export BL_WORKSPACE=your-workspace
export BL_API_KEY=your-api-key

When running on Blaxel itself, authentication is automatic.

Sandbox workflow (primary use case)

This is the most common workflow: create a sandbox, run commands in it, and get a preview URL.

Step 1: Create a sandbox

Use a public image from the Blaxel Hub (https://github.com/blaxel-ai/sandbox/tree/main/hub):

• blaxel/base-image:latest — minimal Linux
• blaxel/node:latest — Node.js
• blaxel/nextjs:latest — Next.js
• blaxel/vite:latest — Vite
• blaxel/expo:latest — Expo (React Native)
• blaxel/py-app:latest — Python

Or use a custom template image you deployed yourself.

Declare the ports you need at creation time. Ports cannot be added after creation. Ports 80, 443, and 8080 are reserved.

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

const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
});