> ## 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

> Configure VibeKit with Blaxel sandboxes for lightning-fast cloud execution

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](https://blaxel.com).

## Installation

First, install the Blaxel provider package:

```bash theme={"dark"}
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](https://blaxel.com)
2. Get your Workspace ID and API Key from the [Blaxel dashboard](https://app.blaxel.com/settings)
3. Set them as environment variables:

```bash theme={"dark"}
export BL_WORKSPACE=YOUR_WORKSPACE_ID
export BL_API_KEY=YOUR_API_KEY
```

Alternatively, you can authenticate using the Blaxel CLI:

```bash theme={"dark"}
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

```typescript theme={"dark"}
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

```typescript theme={"dark"}
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:

```bash theme={"dark"}
# 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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
// 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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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:**

```bash theme={"dark"}
# 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:**

```typescript theme={"dark"}
// 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:**

```typescript theme={"dark"}
// 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:**

```typescript theme={"dark"}
// 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:**

```bash theme={"dark"}
# 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
   ```typescript theme={"dark"}
   // 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
   ```typescript theme={"dark"}
   // 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
   ```typescript theme={"dark"}
   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:

* **Blaxel Platform**: Visit [Blaxel Documentation](https://docs.blaxel.com)
* **VibeKit Integration**: Open an issue on [GitHub](https://github.com/superagent-ai/vibekit/issues)
* **Community Support**: Join our [Discord](https://discord.gg/spZ7MnqFT4)

## Next Steps

* Explore [GitHub integration](../sdk/github-integration) for automated PR workflows
* Learn about [streaming](../sdk/streaming) for real-time command output
* Check out [session management](../sdk/session-management) for persistent workflows