Lifecycle

Stop, start, pause, resume, and automatically sleep persistent VMs

A VM’s name, ID, durable root, and published URLs belong to the persistent resource. Starting it again may create a new runtime, while retaining those identities.

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.

To keep the disk but explicitly discard paused RAM:

beam vm start devbox --cold

The Python equivalents are vm.stop(), vm.start(), vm.pause(), vm.resume(), and vm.start(cold=True).

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 --protected-port 7681

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

from beam import VM

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

Automatic resume wakes a stopped or paused VM on an SDK operation that needs its runtime, authenticated tunnel access, or a permitted request to a published URL. Merely listing or inspecting the VM does not wake it. Without automatic resume, start it explicitly 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:

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())

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.

Python client lifetime and readiness

VM.get(name) resolves state without starting the machine. VM.connect(name) also starts or resumes it. create() and start() wait for exec readiness by default. Use wait(services=True) when you also need SSH, the terminal, and an enabled desktop to be ready.

from beam import VM

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

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.