Give an Agent a Dev Box

A Beam VM is a persistent Linux machine for you or your coding agent. Files, packages, and services stay on its disk between sessions, and it can pause itself when idle and wake on the next request. In about five minutes you’ll create one, put a project on it, open a private URL, and set it to sleep when idle.

Prefer one command? This installs the CLI, signs you in, connects your coding agents, and creates a VM with a browser desktop:

curl -fsSL https://www.beam.cloud/install | sh -s -- --vm

With the CLI already installed, beam setup vm does the same.

If you ran the install command on the introduction page, the CLI is installed and you’re signed in. Skip to Create a VM.

uv tool install beam-client
# If already installed: uv tool upgrade beam-client
beam login

Finish signing in through your browser, then run beam whoami to check your workspace.

Create a VM

beam vm new devbox
beam vm ssh devbox

The default VM has 4 CPUs, 8 GiB of RAM, Ubuntu 24.04, 50 GiB of writable disk, and a browser desktop you can open with beam vm desktop devbox. Type exit to leave SSH. The VM keeps running.

A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep. You’ll set one below.

Put a Project on It

Sync a local directory into /workspace, then run commands there:

mkdir -p app && echo '<h1>Hello from a Beam VM</h1>' > app/index.html
beam vm sync devbox ./app
beam vm exec devbox -- ls /workspace

sync uploads the directory’s contents and needs rsync installed locally. Add --watch to keep uploading as you edit. The whole root disk persists. Files, apt packages, virtual environments, and systemd units are still there after beam vm stop devbox and beam vm start devbox. Start a web server, publish its port as protected, and open it in your browser:

beam vm exec --detach devbox -- python3 -m http.server 8000 --bind 0.0.0.0
beam vm expose devbox 8000 --protected
beam vm open devbox 8000

The URL stays the same across restarts. In a browser, a protected port loads only after you sign in to Beam. Other requests need the VM’s traffic token. To let someone in without signing in, create a link that expires:

beam vm share devbox --port 8000

Anyone with the link can open port 8000 for one hour. Pass --expires-in 10m for a shorter window. Use --public instead of --protected to serve without authentication. See networking for traffic tokens, private port forwarding, and outbound rules.

Sleep When Idle

beam vm update devbox --ttl 300 --idle-action pause --auto-resume

After five idle minutes, the VM pauses: its RAM and running processes are saved, and compute is released. The next SSH session, SDK call, or request to its URL resumes it, with the web server still running. Commands running inside the VM don’t count as activity on their own. Read what counts as activity before you set a timeout on a VM that runs unattended jobs.

Fork It

beam vm fork devbox devbox-experiment
beam vm exec devbox-experiment -- ls /workspace

The fork boots from a copy of the root disk, with its own ID and URLs. Changes in one VM don’t affect the other. Forks don’t copy RAM or running processes, so start services again in the fork.

Hand It to an Agent

Coding agents can do everything above through the Beam MCP server. Run beam setup agent to connect Cursor, Claude Code, Codex, Windsurf, or Claude Desktop, then ask your agent to work on devbox. The VM also comes with the Claude Code and Codex CLIs, so an agent can run on the VM itself. See coding agents for credentials and background sessions. To drive the VM from your own code, connect to it by name:

Python
JavaScript

Install beam-client in your project’s environment with python -m pip install --upgrade beam-client, then run:

from beam import VM

with VM.connect("devbox", context="default") as vm:
    process = vm.process.exec("ls", "/workspace")
    process.wait()
    print(process.stdout.read())

context="default" uses the sign-in from beam login.

Install @beamcloud/beam-js, set BEAM_TOKEN, and run this as an ES module:

import { beamOpts, VM } from "@beamcloud/beam-js";

beamOpts.token = process.env.BEAM_TOKEN || "";
const vm = await VM.connect("devbox");
const command = await vm.exec(["ls", "/workspace"]);
await command.wait();
console.log(await command.stdout.read());
await vm.close();

Secrets bind when you create a VM. To give a VM an API key without putting the key on it, create the secret with the host allowed to receive it:

beam secret create OPENAI_API_KEY "$REAL_OPENAI_API_KEY" --host api.openai.com
beam vm new agentbox --secret OPENAI_API_KEY

The VM sees a placeholder. Beam swaps in the real key only on HTTPS requests to api.openai.com. See VM secrets.

Clean Up

beam vm rm devbox-experiment
beam vm stop devbox

Stopping keeps the disk, and beam vm start devbox boots it again. beam vm rm devbox deletes the VM and its root disk.

Next Steps

Desktop

Screenshot, click, and type in a Linux desktop from Python or JavaScript.

Secrets

Keep real keys off the VM and scope them to approved hosts.

Storage and Snapshots

Save restore points and launch new VMs from templates.

Sandboxes

Run agent code in disposable environments, with GPUs.

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Give an Agent a Dev Box

Create a VM

Put a Project on It

Sleep When Idle

Fork It

Hand It to an Agent

Clean Up

Next Steps

Desktop

Secrets

Storage and Snapshots

Sandboxes

​Install and Sign In

​Create a VM

​Put a Project on It

​Share a Private URL

​Sleep When Idle

​Fork It

​Hand It to an Agent

​Clean Up

​Next Steps

Desktop

Secrets

Storage and Snapshots

Sandboxes

Install and Sign In

Create a VM

Put a Project on It

Share a Private URL

Sleep When Idle

Fork It

Hand It to an Agent

Clean Up

Next Steps