Connect with OAuth
Add this URL to an OAuth-capable MCP client:Authorization: Bearer <token>.
Optional filters: ?features=vm,core for VM tools or ?readonly=true for read-only access. Workspace permissions and approved OAuth scopes apply to every call.
Work with Local Files
Install the CLI, then run:Start Using Beam
Try: “Deploy this project as a stack” or “Create a VM and run my code.” Usewhoami to check your workspace and credits. Your client discovers the available tools; deletions and other destructive operations require confirmation. Apps and stack services scale to zero by default.
VM defaults and images
The CLI and SDKs default to Ubuntu 24.04. With MCP, use the localvm_build_image tool with a Dockerfile such as FROM ubuntu:24.04, then pass the returned image ID to create_vm.spec.image_id. You can also create a VM from a template or snapshot.
For a desktop, set desktop: true in both vm_build_image and create_vm.spec. Desktop images support Ubuntu 24.04 and 22.04 and require at least 1024 MiB RAM.
New MCP VMs default to 4000 millicores (4 CPUs), 8192 MiB RAM, a 50 GiB root disk, and no idle timeout. Enable Docker and SSH explicitly; SSH requires an ssh_public_key matching your private key. Templates and snapshots retain their settings unless you override them. See VM configuration for image and resource options.
VM access
get_vm and vm_ports return the public IPv6 address, stable URLs, and port configuration. Terminal 7681 and enabled desktop 8080 are protected by default. Call vm_access_url with the VM name, protected published HTTP port, and optional lifetime:
beam:credentials; beam:read metadata access does not mint credentials. The link establishes a Secure, HTTP-only cookie on that port’s VM subdomain and redirects to a clean URL. Anyone holding it can access that port until expiry. TTL accepts 1–3600 seconds, default 600; request a fresh link after expiry. vm_rotate_access_token revokes existing sessions. For non-browser HTTP clients, use vm_access_token in X-Beam-VM-Token, not the workspace API token.
vm_expose_port publishes a port; pass protected: true to require authentication. create_vm.spec.public_ports opts out of default terminal/desktop protection; use that only when public access is intended. vm_bind_port and the local vm_port_forward tool provide authenticated TCP access without publishing a URL. See VM networking for direct IPv6 SSH and browser authentication.
Secrets and egress
Containers/pods, functions, endpoints, task queues, and image builds receive real secret values as plaintext environment variables. Create secrets for these workloads withcreate_secret { name, value }; hosts is optional, and setting it does not enable secret proxying for them.
For brokered secrets, call create_secret with approved credential hosts:
create_vm.spec.secrets or vm_exec.secrets. The guest receives a stable placeholder; use it literally in HTTPS request headers on approved hosts. list_secrets returns hosts and placeholders without values. update_secret requires name and value; omit hosts to preserve them, supply a list to replace them, or [] to clear them. Brokered values refresh on the next request after the worker’s 15-second cache expires. Plaintext runtime values refresh at the next container start. VMs and sandboxes receive no automatic workspace token; explicit BETA9_TOKEN/BEAM_TOKEN bindings are plaintext opt-ins.
Set create_vm.spec.allow_list or update_vm.allow_list to up to 64 hostnames, wildcards, IPs, or CIDRs. Hostnames govern TLS on 443 and HTTP on 80; other TCP requires IP/CIDR rules. Proxied private, loopback, and link-local destinations remain blocked, including explicit IP/CIDR targets. An explicit allowlist must cover credential hosts with hostname rules; IP/CIDR rules alone do not cover them. block_network: true permits only bound credential hosts and cannot be combined with an explicit allowlist. Outbound rules do not authenticate inbound ports.