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

> Configure VibeKit with Beam sandboxes for scalable cloud execution

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](https://beam.cloud).

## Installation

First, install the Beam provider package:

```bash theme={"dark"}
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](https://beam.cloud)
2. Get your Beam Token and Workspace ID from the [dashboard](https://platform.beam.cloud/settings/api-keys)
3. Set them as environment variables:

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

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

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

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

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

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

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

```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"}
// 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:**

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

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

```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 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
   ```typescript theme={"dark"}
   // Start small
   cpu: 2,
   memory: "1Gi",
   ```

3. **Clean up promptly**: Always call `kill()` when done to avoid unnecessary charges
   ```typescript theme={"dark"}
   try {
     // Your code here
   } finally {
     await vibeKit.kill();
   }
   ```

## Support

For issues related to:

* **Beam SDK**: Visit [Beam Documentation](https://docs.beam.cloud)
* **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