Create, connect, list and kill
Sandbox.create
Create a machine and resolve once it runs.template is a template ID (agent-browser), a private
snapshot name or a snapshot ID (sn_...). A template ID wins over a snapshot name of the same text. The default
is agent-browser (DEFAULT_TEMPLATE), or universal (FALLBACK_TEMPLATE) on a server without it. A
snapshot that is still being saved is waited for, up to operationTimeoutMs.
SandboxOpts is the connection options plus:
Times are sent as whole seconds.
- Size. A machine is unless
vcpusandmemMiBname another size of your plan (Sizes).GET /v1/orgslists each workspace’s sizes asallowedSpecs. Any other size is400 spec_not_allowed. So is adiskGiBother than the disk the size comes with, so leavediskGiBout. - Resizing later. A paid machine’s disk grows with
PATCH /v1/machines/{id}. Its size (vcpus,memMiB) changes with the samePATCHwhile it is stopped. In a REST body the disk field ispersistentDiskGiB, anddiskGiBthere is400 unknown_field. - Templates. The free plan creates only from . The other templates need a paid
plan and are
403 template_not_allowedon free. A machine from a snapshot is not limited.
No kernel tracing, no nested KVM
No kernel tracing, no nested KVM
The guest kernel has the eBPF syscall and JIT for root only: unprivileged BPF is off, so use
sudo.
Socket, cgroup and XDP programs load. The kernel lacks the tracing side: no kprobes, no ftrace or
tracepoints, and no BTF (/sys/kernel/btf/vmlinux is absent). So bpftrace, BCC tools and
perf probe do not work.There is also no /dev/kvm in the guest, because the kernel is a KVM guest, not a KVM host. So
Firecracker, QEMU with KVM, Docker-in-VM runtimes that need KVM, and nested microVMs cannot run. QEMU in
pure emulation (-accel tcg) works, slowly.Sandbox.connect
Attach to an existing machine, and resume it if it is paused or stopped.resume: false attaches without waking the machine. envs works as in create.
Sandbox.list
List your machines, every page of them.metadata keeps only the machines that have every given key and value.
Sandbox.kill
Delete a machine and its disks.false if the machine did not exist.
Snapshots
sbx.createSnapshot saves a snapshot. See Snapshots.
Sandbox.listSnapshots
List your private snapshots.Sandbox.getSnapshot
Get one snapshot.Sandbox.deleteSnapshot
Delete a snapshot.false if the snapshot was already gone.
The Sandbox object
Lifecycle calls (create, connect, pause, resume, stop, kill) wait for the server’s operation to
finish, up to operationTimeoutMs.
sbx.getInfo
Get the machine’s current state from the server.SandboxInfo has sandboxId, templateId, snapshotId?, name,
metadata, vault, startedAt, archiveAt?, autoSuspendMs?, state and machine (the raw API
object). state is one of:
suspended. The vault field describes personal Vault delivery. Org Secret
selections and delivery status are at GET /v1/machines/{id}/secrets, independent of Vault. The
Secrets CLI and HTTP API manage them.
sbx.isRunning
Check whether the machine runs.true if state is running.
sbx.pause
Save memory and pause the machine.sbx.resume
Resume a paused machine, or start a stopped one.sbx.stop
Shut the machine down: processes end, and/data is kept.
sbx.setAutoSuspend
Set how long the machine stays idle before it pauses.0 turns the idle pause
off. A part minute or a value outside that range is refused. The free plan keeps
minutes and refuses another value. The setting is kept across pause and resume. See
Auto-pause.
sbx.setMetadata
Replace the machine’s labels.{} clears them.
sbx.createSnapshot
Save the machine’s disks as a private snapshot.CreateSnapshotOpts has name (required), description, and rootOnly to save only the root disk.
From a running machine, the snapshot comes back with status: 'pending' and turns ready once saved.
A machine created from the snapshot is a copy of the disks:
secrets does not enroll the copy in Secrets. vault: false turns off only Vault delivery. To select
Secrets explicitly, use the CLI or the HTTP API (Secrets).
sbx.sshCredentials
Get a short-lived SSH certificate forpublicKey.
ttlSeconds is 1 to 86 400 (default 1 hour). SshCredentials has host, port, username (the machine ID), certificate
(save it as <key>-cert.pub), knownHostsLine, expiresAt and connectionId. See SSH.
sbx.kill
Delete the machine and its disks.false if the machine was already gone.