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.

Beam is a serverless platform for deploying and running containerized applications in secure cloud sandboxes. Built for AI agents and compute-intensive workloads, Beam provides on-demand scalability with automatic resource management. Learn more at beam.cloud.

​
Installation

First, install the Beam provider package: 
npm install @vibe-kit/beam

​
Prerequisites

Before using the Beam provider, you need to:
  1. Sign up for a Beam account at https://beam.cloud
  2. Get your Beam Token and Workspace ID from the dashboard
  3. Set them as environment variables:
export BEAM_TOKEN=YOUR_BEAM_TOKEN
export BEAM_WORKSPACE_ID=YOUR_WORKSPACE_ID

​
Configuration

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

​
Using the provider directly

import { VibeKit } from "@vibe-kit/sdk";
import { createBeamProvider } from "@vibe-kit/beam";

// Create the Beam provider with configuration
const beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  cpu: 2, // optional, defaults to 2
  memory: "1Gi", // optional, defaults to "1Gi"
  keepWarmSeconds: 300, // optional, defaults to 300 (5 minutes)
});

// 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(beamProvider)
  .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: {
    beam: {
      // Required Beam authentication
      token: process.env.BEAM_TOKEN!,
      workspaceId: process.env.BEAM_WORKSPACE_ID!,

      // Optional resource configuration
      cpu: 4,
      memory: "2Gi",
      keepWarmSeconds: 600,

      // Optional custom Docker image
      image: "my-custom-image:latest"
    },
  },
};

​
Configuration Options

The createBeamProvider function accepts these configuration options:

​
Required Options

  • token (string): Your Beam authentication token from the dashboard
  • workspaceId (string): Your Beam workspace ID

​
Optional Options

  • image (string): Custom Docker image. If not provided, it will be auto-selected based on the agent type:
    • claude → superagentai/vibekit-claude:1.0
    • codex → superagentai/vibekit-codex:1.0
    • opencode → superagentai/vibekit-opencode:1.0
    • gemini → superagentai/vibekit-gemini:1.1
    • grok → superagentai/vibekit-grok-cli:1.0
    • Default: ubuntu:22.04
  • cpu (number): Number of CPU cores to allocate (default: 2)
  • memory (number | string): Memory allocation, e.g., 1024 or “1Gi” (default: “1Gi”)
  • keepWarmSeconds (number): How long to keep the sandbox warm after inactivity (default: 300 seconds / 5 minutes)

​
ENV variables and secrets

Configure your Beam provider using environment variables: 
# Required Beam credentials
BEAM_TOKEN=your_beam_token_here
BEAM_WORKSPACE_ID=your_workspace_id_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 beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  // All other config is optional
});

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

​
Unique Features

​
Automatic Image Selection

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

​
Serverless Scalability

  • On-demand resources - Sandboxes spin up automatically when needed
  • Automatic scaling - Resources scale based on workload
  • Pay-per-use - Only pay for actual compute time used
  • No infrastructure management - Beam handles all server provisioning and maintenance

​
Performance Optimization

  • Fast cold starts - Optimized container initialization
  • Keep-warm configuration - Keep sandboxes warm between requests for faster response times
  • Configurable resources - Adjust CPU and memory per workload
  • Port exposure - Dynamically expose ports for web services

​
Advanced Usage

​
Custom Docker Image

Use your own Docker image with pre-installed dependencies: 
const beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  image: "my-registry/my-custom-image:latest",
});

​
High-Performance Configuration

For compute-intensive workloads: 
const beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  cpu: 8,
  memory: "16Gi",
  keepWarmSeconds: 600, // 10 minutes
});

​
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: 
// 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}`);

​
System Requirements

  • Node.js 18+ - Runtime environment
  • Beam account - Active account with API credentials
  • Internet connection - Required for cloud sandbox execution

​
Limitations

  • Pause/Resume: Beam doesn’t directly support pause/resume operations. The sandbox remains active until terminated. Use keepWarmSeconds to manage idle timeouts and optimize costs.
  • Beta SDK: The Beam TypeScript SDK is currently in beta. Some features may change in future releases.
  • Cold start time: Initial sandbox creation may take a few seconds. Use keepWarmSeconds to maintain warm sandboxes for faster subsequent executions.

​
Troubleshooting

Authentication errors: 
# Verify your credentials are set correctly
echo $BEAM_TOKEN
echo $BEAM_WORKSPACE_ID

# Re-export if needed
export BEAM_TOKEN=your_token_here
export BEAM_WORKSPACE_ID=your_workspace_id_here
Sandbox creation timeout: 
// Increase CPU/memory for faster initialization
const beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  cpu: 4,
  memory: "2Gi",
});
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 beamProvider = createBeamProvider({
  token: process.env.BEAM_TOKEN!,
  workspaceId: process.env.BEAM_WORKSPACE_ID!,
  image: "ubuntu:22.04", // Use a reliable base image
});

​
Cost Optimization Tips

  1. Use keep-warm wisely: Set keepWarmSeconds based on your usage pattern
    • High frequency: 600+ seconds (10+ minutes)
    • Low frequency: 300 seconds (5 minutes) or less
  2. Right-size resources: Start with minimal resources and scale up as needed 
    // Start small
cpu: 2,
memory: "1Gi",
  3. Clean up promptly: Always call kill() when done to avoid unnecessary charges 
    try {
  // Your code here
} finally {
  await vibeKit.kill();
}

​
Support

For issues related to:

​
Next Steps