Lifecycle

JavaScript examples use @beamcloud/beam-js 1.1.0 or later. Configure the SDK before running them. A VM keeps its name, ID, durable root, and published URLs across restarts. Its runtime and container ID may change.

Inspect state

beam vm list
beam vm get devbox
beam vm list --status stopped --json

list displays CPU, memory, configured root disk size, and uptime for the current running boot. get --json includes the specification, state, current container ID, and URLs. States include starting, running, stopping, stopped, paused, and error.

Operation	Persistent filesystem	RAM and processes	Compute after completion
Stop	Saved	Discarded	Released
Start a stopped VM	Restored	New boot; enabled systemd services start	Running
Pause	Saved with the memory checkpoint	Saved	Released
Resume a paused VM	Restored with its saved RAM	Restored	Running
Start with `--cold`	Retained	Saved RAM discarded; new boot	Running
Snapshot	Captured as a restore point	Not included	Current VM keeps its state
Fork	Copied to an independent root	New boot	A new VM runs
Remove	VM root deleted	Discarded	Released

Stop and start

beam vm stop devbox
beam vm start devbox

Stop saves the latest root contents before releasing compute and creates a filesystem snapshot artifact by default. Start cold-boots the saved filesystem. A command you launched manually does not rerun on a cold boot; install a systemd service if it should start automatically. --no-snapshot skips the named snapshot artifact, while still saving the durable root:

beam vm stop devbox --no-snapshot
beam vm start devbox

Pause and resume

beam vm pause devbox
beam vm resume devbox

Pause checkpoints memory and its paired disks, then shuts down the microVM. Resume restores those processes and memory. beam vm start also resumes a paused VM; resume is an alias for start. External network peers can close connections while the VM is paused. Applications should reconnect their database, API, and other external sessions after resuming. Discard the saved RAM and boot from the disk:

beam vm start devbox --cold

The Python equivalents are vm.stop(), vm.start(), vm.pause(), vm.resume(), and vm.start(cold=True). JavaScript uses the same lifecycle names, with await vm.start({ cold: true }) for a cold boot.

Idle TTL and automatic resume

Unlike a sandbox lifetime, a VM TTL measures idle time. It does not delete the VM.

beam vm new devbox --ttl 300 --auto-resume

After 300 idle seconds, the default action saves the root and stops the VM. Set --idle-action pause to preserve RAM instead:

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

Python
JavaScript

from beam import VM

vm = VM.get("devbox")
vm.update(ttl=300, idle_action="pause", auto_resume=True)
vm.close()

const vm = await VM.get("devbox");
await vm.update({ idleTimeout: 300, idleAction: "pause", autoResume: true });
await vm.close();

With automatic resume enabled, SDK guest operations, authenticated tunnels, and permitted requests to published URLs wake a stopped or paused VM. Listing or inspecting the VM does not wake it. Without automatic resume, start it before executing commands or using a URL. Disable idle sleep or automatic resume separately:

beam vm update devbox --ttl 0
beam vm update devbox --no-auto-resume

What counts as activity?

Foreground CLI execution, SSH/tunnels, and active desktop or terminal WebSockets keep an activity lease. SDK access to processes or files updates activity. A command running inside the guest by itself is not a continuous activity signal. For a long Python operation on an idle-limited VM, hold a lease:

Python
JavaScript

from beam import VM

with VM.get("devbox") as vm:
    with vm.keep_alive():
        process = vm.process.exec("bash", "-lc", "./long-build.sh")
        for line in process.logs:
            print(line, end="")
        print(process.wait())

const vm = await VM.connect("devbox");
await vm.keepAlive(async () => {
  const command = await vm.exec(["bash", "-lc", "./long-build.sh"]);
  for await (const line of command.logs) console.log(line);
  console.log(await command.wait());
});
await vm.close();

Detached commands and background coding agents do not keep the VM awake for their entire lifetime. Disable the TTL for unattended jobs, or keep an SDK activity lease open until the job finishes.

SDK client lifetime and readiness

VM.get(name) reads the VM’s state without starting it. VM.connect(name) also starts or resumes it. To wait for SSH, the browser terminal, or an enabled desktop, use Python vm.wait(services=True) or JavaScript await vm.wait({ services: true }). Desktop and Docker SDK helpers wait automatically.

Python
JavaScript

from beam import VM

with VM.connect("devbox") as vm:
    vm.wait(services=True)
    print(vm.info["status"])

const vm = await VM.connect("devbox");
await vm.wait({ services: true });
console.log(vm.status);
await vm.close();

close() and exiting a with VM... block release local client connections. They leave the VM running. Use stop(), pause(), or remove() to release compute.

Remove a VM

beam vm rm devbox

Removal deletes the VM and its root disk. Saved snapshot and template artifacts, additional named disks, and shared volumes are managed separately. Use beam vm snapshot rm and beam vm template rm to remove artifacts you no longer need.

Troubleshooting

Symptom	Next step
`VM is not running`	Run `beam vm start NAME`, or enable automatic resume.
VM is starting or in an error state	Inspect `beam vm get NAME --json` for the error and configuration. Verify that your selected pool supports CPU microVMs and has capacity.
Service is unavailable after a cold boot	Inspect `beam vm logs NAME --unit SERVICE` and make sure the unit is enabled.
Browser access fails after sleeping	Start the VM, then reopen it with `beam vm desktop NAME` or `beam vm terminal NAME` to obtain a fresh protected session.
VM slept while a background job was working	Set `--ttl 0` or hold `vm.keep_alive()` during the job.
Wrong workspace or gateway	Check `beam whoami` and `beam config list`; use `beam --context CONTEXT vm get NAME`.

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Inspect state

Stop and start

Pause and resume

Idle TTL and automatic resume

What counts as activity?

SDK client lifetime and readiness

Remove a VM

Troubleshooting

​Inspect state

​Stop and start

​Pause and resume

​Idle TTL and automatic resume

​What counts as activity?

​SDK client lifetime and readiness

​Remove a VM

​Troubleshooting

Inspect state

Stop and start

Pause and resume

Idle TTL and automatic resume

What counts as activity?

SDK client lifetime and readiness

Remove a VM

Troubleshooting