> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Beam CLI, sign in, and connect coding agents to the Beam MCP server with `curl -fsSL https://www.beam.cloud/install | sh`. To also create a VM, run `curl -fsSL https://www.beam.cloud/install | sh -s -- --vm`.
> VMs are persistent Linux machines without GPUs. Defaults: 4 CPUs, 8 GiB of RAM, a 50 GiB disk, Ubuntu 24.04, and a browser desktop. A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep.
> Stopping a VM keeps its disk and discards RAM and processes. Pausing keeps both, and resuming restores them. To pause after 5 idle minutes and wake on access, run `beam vm update NAME --ttl 300 --idle-action pause --auto-resume`.
> Core VM commands: `beam vm new NAME`, `beam vm ssh NAME`, `beam vm sync NAME ./dir`, `beam vm exec NAME -- CMD`, `beam vm expose NAME PORT --protected`, `beam vm fork NAME NEW_NAME`, `beam vm pause NAME`, `beam vm stop NAME`, `beam vm rm NAME`.
> For GPUs, use a sandbox or a deployed endpoint. Sandboxes are disposable environments that boot in seconds and fork from snapshots.
> Current rates are at https://www.beam.cloud/pricing.

# GitHub Actions Runners

> Run GitHub Actions jobs on managed Ubuntu VMs with Docker and a warm dependency cache

Beam Runners use high-performance gaming machines and often run CI jobs **2–3× faster than GitHub-hosted Runners**.

Beam starts a fresh Ubuntu 24.04 VM with Docker and Compose for each GitHub Actions job and deletes it when the job ends. Move an existing Linux job to Beam by changing its `runs-on` label.

## Set up a Runner

1. Open **Virtual Machines → GitHub Runners** in the [Beam dashboard](https://platform.beam.cloud/vms?tab=runners) and select **Connect GitHub**.
2. Install the Beam GitHub App on your personal account or an organization you own. Grant it access to the repositories you want to run on Beam. If the app is already installed, select that account in Beam.
3. Set `runs-on` to a single Beam label in your workflow. Run the workflow and check the job in the **GitHub Runners** tab.

```yaml theme={null}
jobs:
  test:
    runs-on: beam-4vcpu-ubuntu-2404
    steps:
      - uses: actions/checkout@v7
      - run: make test
```

## Runner sizes and pricing

Beam bills Runner compute by the second while the VM is running. Each size includes 50 GiB of writable disk. The table uses published [Beam Performance tier rates](https://www.beam.cloud/pricing#cpu-capacity), expressed per minute.

| `runs-on` label | RAM | USD/min |
| - | -: | -: |
| `beam-2vcpu-ubuntu-2404` | 8 GiB | \$0.003 |
| `beam-4vcpu-ubuntu-2404` | 16 GiB | \$0.006 |
| `beam-8vcpu-ubuntu-2404` | 32 GiB | \$0.012 |
| `beam-16vcpu-ubuntu-2404` | 64 GiB | \$0.024 |
| `beam-32vcpu-ubuntu-2404` | 128 GiB | \$0.048 |

At 2 vCPU, Beam's Linux x64 rate is **25% lower than Blacksmith** (\$0.004/min) and **50% lower than GitHub-hosted Runners** (\$0.006/min). This compares paid list rates before included usage. See [Blacksmith pricing](https://www.blacksmith.sh/pricing) and [GitHub Actions Runner pricing](https://docs.github.com/en/billing/reference/actions-runner-pricing).

## Runner capacity

Beam starts Runners on demand. Each workspace can have **100 concurrent Runners by default**, including Runners that are starting. The workspace's CPU limit and available compute also affect how many jobs can run at once.

Jobs stay queued in GitHub until a Runner is available. The **GitHub Runners** tab shows how many Runners are in use, your workspace's Runner limit, and why jobs are waiting.

## Enhanced cache

Enhanced cache uses Beam's content-addressed storage to automatically reuse build artifacts and downloaded dependencies across jobs in the same repository. It covers Go build outputs and modules, npm packages, and pip downloads. It's on by default and requires no workflow changes.

Successful jobs from pushes to the default branch or scheduled runs on that branch populate the cache. Manage it under **GitHub Runners → Settings**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.