> ## 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. # Give an Agent a Dev Box > Create a persistent VM, put a project on it, share a private URL, and let it sleep when idle 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. > [!TIP] > > Prefer one command? This installs the CLI, signs you in, connects your coding agents, and creates a VM with a browser desktop: > > ```bash theme={null} > curl -fsSL https://www.beam.cloud/install | sh -s -- --vm > ``` > > With the CLI already installed, `beam setup vm` does the same. ## Install and Sign In If you ran the install command on the [introduction](/v2/getting-started/introduction) page, the CLI is installed and you're signed in. Skip to [Create a VM](#create-a-vm). ```bash theme={null} 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 ```bash theme={null} 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. > [!NOTE] > > 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: ```bash theme={null} mkdir -p app && echo '

Hello from a Beam VM

' > 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`. ## Share a Private URL Start a web server, publish its port as protected, and open it in your browser: ```bash theme={null} 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: ```bash theme={null} 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](/v2/vm/networking) for traffic tokens, private port forwarding, and outbound rules. ## Sleep When Idle ```bash theme={null} 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](/v2/vm/lifecycle#what-counts-as-activity) before you set a timeout on a VM that runs unattended jobs. ## Fork It ```bash theme={null} 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](/v2/vm/processes#coding-agents) for credentials and background sessions. To drive the VM from your own code, connect to it by name: **Python** Install `beam-client` in your project's environment with `python -m pip install --upgrade beam-client`, then run: ```python theme={null} 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`. **JavaScript** Install `@beamcloud/beam-js`, set `BEAM_TOKEN`, and run this as an ES module: ```javascript theme={null} 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(); ``` > [!TIP] > > 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: > > ```bash theme={null} > 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](/v2/vm/secrets). ## Clean Up ```bash theme={null} 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](/v2/vm/desktop)** > > Screenshot, click, and type in a Linux desktop from Python or JavaScript. > **[Secrets](/v2/vm/secrets)** > > Keep real keys off the VM and scope them to approved hosts. > **[Storage and Snapshots](/v2/vm/storage)** > > Save restore points and launch new VMs from templates. > **[Sandboxes](/v2/getting-started/quickstart-sandbox)** > > Run agent code in disposable environments, with GPUs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.