Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt

Use this file to discover all available pages before exploring further.

When you call vm.run(...) or vm.put_file(...), SmolVM has to send that command into the sandbox and read the result back. The connection it uses for this is the control channel. SmolVM supports two: the long-standing SSH channel and a newer vsock channel that skips the network entirely. You usually don’t need to choose — SmolVM picks the right one for you.

​
What this means for you

  • You don’t have to change anything. SmolVM auto-selects the best channel for your host and image.
  • First command runs sooner. On Linux QEMU hosts with a recent image, vsock is ready seconds after boot, before SSH is.
  • No new ports or keys. vsock is a host-to-guest socket — it does not use TCP, your network, or SSH keys.
  • SSH still works the same. smolvm ssh and expose_local() continue to use real SSH.

​
When each channel is used

SmolVM resolves the control channel in this order:
  1. Explicit request — SmolVM(comm_channel="ssh" | "vsock") or the --comm-channel CLI flag.
  2. VM config — a channel previously persisted on the sandbox.
  3. Auto — vsock on Linux + QEMU hosts when the guest agent answers; SSH everywhere else.
Host / backendDefault channel
Linux + QEMU, recent imagevsock (falls back to SSH)
Linux + FirecrackerSSH
macOS + QEMUSSH (vsock not available on macOS)
Windows guestSSH
vsock currently requires the QEMU backend on a Linux host with vhost_vsock loaded, and a sandbox image that ships the SmolVM guest agent (locally built images already include it).

​
Why vsock is faster

SSH on QEMU rides over the same NAT’d network your sandbox uses for the internet. The first command has to wait for:
  1. The guest network coming up
  2. cloud-init finishing
  3. sshd accepting connections
  4. A TCP banner exchange
vsock is a direct host-to-guest socket built into the hypervisor. The SmolVM guest agent listens on it from /init, before sshd even starts — so the first command can run as soon as the kernel is up.

​
SDK usage

The comm_channel keyword is available on both SmolVM(...) and SmolVM.from_id(...). Leave it unset to use auto-selection. 
from smolvm import SmolVM

# Auto (recommended) — vsock when available, else SSH.
with SmolVM() as vm:
    print(vm.run("uname -a").stdout)

# Force vsock. Raises if the guest agent does not answer.
with SmolVM(comm_channel="vsock") as vm:
    print(vm.run("uname -a").stdout)

# Force SSH (the previous behavior).
with SmolVM(comm_channel="ssh") as vm:
    print(vm.run("uname -a").stdout)
Reconnecting to a running sandbox keeps the same kwarg: 
vm = SmolVM.from_id("agent-001", comm_channel="vsock")
vm.run("ls /workspace")
comm_channel="vsock" is strict — if the guest agent isn’t reachable, SmolVM raises rather than silently falling back. Use the default (auto) if you want graceful fallback to SSH.

​
CLI usage

The --comm-channel flag is available on smolvm file upload, smolvm file download, and the smolvm env subcommands: 
# Upload a file over vsock (skips SSH entirely)
smolvm file upload my-vm ./report.csv /workspace/report.csv --comm-channel vsock

# Set env vars over the default (auto) channel
smolvm env set my-vm OPENAI_API_KEY=sk-...

# Force SSH for a one-off command
smolvm env list my-vm --comm-channel ssh
smolvm ssh always opens a real interactive SSH session and does not accept --comm-channel.

​
Platform support

PlatformvsockSSH
Linux + QEMU + recent SmolVM image✅✅
Linux + Firecracker❌ (not wired yet)✅
macOS❌ (no vhost-vsock)✅
Windows guests❌✅
If vsock isn’t supported on your platform, SmolVM uses SSH automatically — no configuration needed.

​
Troubleshooting

Make sure the vhost_vsock kernel module is loaded and the image you booted contains the SmolVM guest agent. Locally built images include it; older published images may not until they are republished.
sudo modprobe vhost_vsock
lsmod | grep vsock
Pass comm_channel="ssh" to SmolVM(...) (or --comm-channel ssh on the CLI) for the calls that should use SSH. There is no global override — the kwarg is per-VM by design.
Some operations always use SSH:
  • smolvm ssh (interactive shell)
  • vm.expose_local(...) (port forwarding rides the SSH tunnel)
This is expected. Control-plane traffic (run, file transfer, env vars) moves to vsock when available; the SSH tunnel stays for data-plane forwarding.

​
Next steps

Last modified on May 30, 2026