Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Sign up for a Blaxel account at https://blaxel.com
  2. Get your Workspace ID and API Key from the Blaxel dashboard
  3. 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

  1. 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
  2. Leverage automatic scale-to-zero: Blaxel automatically puts sandboxes in standby mode when idle, reducing costs without manual intervention
  3. Right-size memory: Start with minimal memory and scale up as needed 
    // Start small
memory: 4096, // 4GB

// Scale up if needed
memory: 8192, // 8GB
  4. Clean up promptly: Always call kill() when done to avoid unnecessary charges 
    try {
  // Your code here
} finally {
  await vibeKit.kill();
}
  5. Use CLI authentication: For local development, use bl login to avoid storing credentials in code

​
Support

For issues related to:

​
Next Steps