Blaxel

Blaxel is a cloud-based container platform optimized for AI agents and development workflows. With sub-25ms cold starts from standby mode and automatic scale-to-zero, Blaxel provides cost-effective, high-performance sandboxes for running AI-generated code. Learn more at blaxel.com.

Installation

First, install the Blaxel provider package:

npm install @vibe-kit/blaxel

Prerequisites

Before using the Blaxel provider, you need to:

Sign up for a Blaxel account at https://blaxel.com
Get your Workspace ID and API Key from the Blaxel dashboard
Set them as environment variables:

export BL_WORKSPACE=YOUR_WORKSPACE_ID
export BL_API_KEY=YOUR_API_KEY

Alternatively, you can authenticate using the Blaxel CLI:

npm install -g @blaxel/cli
bl login

Configuration

VibeKit uses a builder pattern with method chaining for type safety and flexibility. Configure your Blaxel provider and VibeKit instance:

Using the provider directly

import { VibeKit } from "@vibe-kit/sdk";
import { createBlaxelProvider } from "@vibe-kit/blaxel";

// Create the Blaxel provider with configuration
const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  memory: 4096, // optional, defaults to 4096 MB
  region: "us-pdx-1", // optional, Blaxel will choose default
  ttl: "24h", // optional, auto-delete after 24 hours
});

// Create the VibeKit instance with the provider
const vibeKit = new VibeKit()
  .withAgent({
    type: "claude",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-sonnet-4-20250514",
  })
  .withSandbox(blaxelProvider)
  .withWorkingDirectory("/workspace") // Optional: specify working directory
  .withSecrets({
    // Any environment variables for the sandbox
    NODE_ENV: "production",
  });

// Generate code
const result = await vibeKit.generateCode({
  prompt: "Create a REST API with Express.js",
  mode: "ask"
});

// Execute commands in the sandbox
const response = await vibeKit.executeCommand("npm install && npm test");
console.log(response);

// Start a development server
await vibeKit.executeCommand("npm run dev", { background: true });

// Get the public URL for the service
const url = await vibeKit.getHost(3000);
console.log(`Service available at: ${url}`);

// Clean up
await vibeKit.kill();

Using configuration object

import { VibeKit, VibeConfig } from "@vibe-kit/sdk";

const config: VibeConfig = {
  ...,
  environment: {
    blaxel: {
      // Required Blaxel authentication
      workspace: process.env.BL_WORKSPACE!,
      apiKey: process.env.BL_API_KEY!,

      // Optional resource configuration
      memory: 8192,
      region: "us-pdx-1",
      ttl: "48h",

      // Optional custom Docker image
      image: "my-custom-image:latest",
      
      // Optional port configuration
      ports: [
        { target: 3000, name: "web-server" },
        { target: 8080, name: "api-server" }
      ]
    },
  },
};

Configuration Options

The createBlaxelProvider function accepts these configuration options:

Required Options

workspace (string): Your Blaxel workspace ID from the dashboard (can be omitted if using CLI authentication)
apiKey (string): Your Blaxel API key (can be omitted if using CLI authentication)

Optional Options

image (string): Custom Docker image. If not provided, it will be auto-selected based on the agent type:
- claude → blaxel/vibekit-claude
- codex → blaxel/vibekit-codex
- opencode → blaxel/vibekit-opencode
- gemini → blaxel/vibekit-gemini
- grok → blaxel/vibekit-grok
- Default: blaxel/vibekit-codex
memory (number): Memory allocation in MB (default: 4096)
region (string): Deployment region (e.g., “us-pdx-1”, “eu-west-1”). If not specified, Blaxel chooses the optimal region automatically
ttl (string): Time-to-live for automatic sandbox cleanup (e.g., “24h”, “30m”, “7d”). Supported units: s (seconds), m (minutes), h (hours), d (days), w (weeks)
ports (array): Port configuration for exposing services. Default: [{ target: 3000, name: "web-server" }]

ENV variables and secrets

Configure your Blaxel provider using environment variables:

# Required Blaxel credentials
BL_WORKSPACE=your_workspace_id_here
BL_API_KEY=your_api_key_here

# Agent API keys
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key
GEMINI_API_KEY=your_gemini_key
GROK_API_KEY=your_grok_key

# Optional GitHub integration
GITHUB_TOKEN=your_github_token_here

Reference them in your code:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  // All other config is optional
});

// GitHub configuration at SDK level
const vibeKit = new VibeKit()
  .withSandbox(blaxelProvider)
  .withGithub({
    token: process.env.GITHUB_TOKEN,
    repository: "owner/repo-name",
  });

Unique Features

Lightning-Fast Cold Starts

Blaxel’s innovative architecture enables sub-25ms cold starts from standby mode, making it one of the fastest sandbox providers available. This means near-instant resumption of sandboxes after periods of inactivity.

Automatic Scale-to-Zero

Cost optimization - Sandboxes automatically enter standby mode when inactive
Instant resume - Sub-25ms wake-up time from standby
No manual management - Blaxel handles lifecycle automatically
TTL-based cleanup - Set automatic deletion timers to prevent resource waste

Automatic Image Selection

Blaxel automatically selects the appropriate pre-built Docker image based on your agent type, ensuring optimal compatibility and performance without manual configuration.

Performance Features

Fast execution - Optimized container runtime for AI workloads
Flexible resources - Configure memory allocation per sandbox
Port exposure - Dynamically expose ports for web services
Background processes - Run long-running commands in the background

Advanced Usage

Custom Docker Image

Use your own Docker image with pre-installed dependencies:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  image: "my-registry/my-custom-image:latest",
});

High-Memory Configuration

For memory-intensive workloads:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  memory: 16384, // 16GB
  ttl: "48h", // Keep for 2 days
});

Background Command Execution

Run long-running processes in the background:

// Start a background process
await vibeKit.executeCommand("npm run dev", { background: true });

// The command runs independently
// You can continue with other operations

// Get the host URL to access the running service
const url = await vibeKit.getHost(3000);
console.log(`Dev server running at: ${url}`);

Exposing Multiple Ports

Expose multiple services running on different ports:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  ports: [
    { target: 3000, name: "frontend" },
    { target: 8000, name: "api" },
    { target: 5432, name: "database" },
  ],
});

// Start services on different ports
await vibeKit.executeCommand("npm run api", { background: true });
await vibeKit.executeCommand("npm run frontend", { background: true });

// Get URLs for each service
const apiUrl = await vibeKit.getHost(8000);
const frontendUrl = await vibeKit.getHost(3000);

console.log(`API: ${apiUrl}`);
console.log(`Frontend: ${frontendUrl}`);

Regional Deployment

Deploy to specific regions for lower latency:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  region: "eu-west-1", // Deploy to Europe
});

Time-to-Live Management

Set automatic cleanup timers to manage costs:

const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  ttl: "2h", // Auto-delete after 2 hours
});

// For development/testing - short TTL
const devProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  ttl: "30m", // Auto-delete after 30 minutes
});

// For production - longer TTL
const prodProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  ttl: "7d", // Auto-delete after 7 days
});

System Requirements

Node.js 18+ - Runtime environment
Blaxel account - Active account with workspace and API key
Internet connection - Required for cloud sandbox execution

Limitations

Pause/Resume: Blaxel automatically handles standby mode, so manual pause operations are not required. Sandboxes automatically enter standby when inactive and resume in sub-25ms when needed.
Resource limits: Memory and CPU resources are based on your Blaxel plan tier. Check your dashboard for current limits.

Troubleshooting

Authentication errors:

# Verify your credentials are set correctly
echo $BL_WORKSPACE
echo $BL_API_KEY

# Re-export if needed
export BL_WORKSPACE=your_workspace_id_here
export BL_API_KEY=your_api_key_here

# Or login via CLI
bl login

Sandbox creation timeout:

// Increase memory for faster initialization
const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  memory: 8192, // Increase from default 4096
});

Port exposure issues:

// Ensure the service is running before calling getHost
await vibeKit.executeCommand("npm start", { background: true });

// Wait a moment for the service to start
await new Promise(resolve => setTimeout(resolve, 2000));

// Then get the host URL
const url = await vibeKit.getHost(3000);

Image pull errors:

// Specify a custom image if default images aren't accessible
const blaxelProvider = createBlaxelProvider({
  workspace: process.env.BL_WORKSPACE!,
  apiKey: process.env.BL_API_KEY!,
  image: "ubuntu:22.04", // Use a reliable base image
});

Region availability:

# List available regions using Blaxel CLI
bl regions list

# Or let Blaxel choose automatically by omitting the region parameter

Cost Optimization Tips

Use TTL wisely: Set appropriate TTL values based on your usage pattern

// Development/testing - short TTL
ttl: "30m" // 30 minutes

// Production workflows - longer TTL
ttl: "24h" // 24 hours

Leverage automatic scale-to-zero: Blaxel automatically puts sandboxes in standby mode when idle, reducing costs without manual intervention

Right-size memory: Start with minimal memory and scale up as needed

// Start small
memory: 4096, // 4GB

// Scale up if needed
memory: 8192, // 8GB

Clean up promptly: Always call kill() when done to avoid unnecessary charges

try {
  // Your code here
} finally {
  await vibeKit.kill();
}

Use CLI authentication: For local development, use bl login to avoid storing credentials in code

Support

For issues related to:

Blaxel Platform: Visit Blaxel Documentation
VibeKit Integration: Open an issue on GitHub
Community Support: Join our Discord

Next Steps

Explore GitHub integration for automated PR workflows
Learn about streaming for real-time command output
Check out session management for persistent workflows

Get Started

Agents

Supported Sandboxes

SDK Reference

Installation

Prerequisites

Configuration

Using the provider directly

Using configuration object

Configuration Options

Required Options

Optional Options

ENV variables and secrets

Unique Features

Lightning-Fast Cold Starts

Automatic Scale-to-Zero

Automatic Image Selection

Performance Features

Advanced Usage

Custom Docker Image

High-Memory Configuration

Background Command Execution

Exposing Multiple Ports

Regional Deployment

Time-to-Live Management

System Requirements

Limitations

Troubleshooting

Cost Optimization Tips

Support

Next Steps

​Installation

​Prerequisites

​Configuration

​Using the provider directly

​Using configuration object

​Configuration Options

​Required Options

​Optional Options

​ENV variables and secrets

​Unique Features

​Lightning-Fast Cold Starts

​Automatic Scale-to-Zero

​Automatic Image Selection

​Performance Features

​Advanced Usage

​Custom Docker Image

​High-Memory Configuration

​Background Command Execution

​Exposing Multiple Ports

​Regional Deployment

​Time-to-Live Management

​System Requirements

​Limitations

​Troubleshooting

​Cost Optimization Tips

​Support

​Next Steps

Installation

Prerequisites

Configuration

Using the provider directly

Using configuration object

Configuration Options

Required Options

Optional Options

ENV variables and secrets

Unique Features

Lightning-Fast Cold Starts

Automatic Scale-to-Zero

Automatic Image Selection

Performance Features

Advanced Usage

Custom Docker Image

High-Memory Configuration

Background Command Execution

Exposing Multiple Ports

Regional Deployment

Time-to-Live Management

System Requirements

Limitations

Troubleshooting

Cost Optimization Tips

Support

Next Steps