Control channel - Celesto AI

SmolVM needs a way to talk to each sandbox after it starts. That connection is the control channel, and SmolVM chooses the fastest supported channel for you.

What you can do

The control channel powers:

vm.run(...) in the Python SDK
smolvm sandbox shell for a fast interactive shell
smolvm sandbox file upload and smolvm sandbox file download
smolvm sandbox env set, unset, and list
Snapshot preflight work that asks the guest to save files before the VM pauses

SmolVM supports two channels:

Channel	What it is	Best for
SSH	A normal secure shell connection over the sandbox network	Maximum compatibility, Windows guests, manual SSH access
vsock	A direct host-to-guest socket that skips TCP networking	Fast commands, file transfer, shell access, and guest sync on supported Linux guests

Default channel selection

SmolVM resolves the channel in this order:

Explicit request - SmolVM(comm_channel="ssh") or SmolVM(comm_channel="vsock")
Saved VM config - a channel stored with the sandbox
Automatic choice - vsock where the host and guest support it, SSH elsewhere

Host and backend	Automatic channel
Linux + QEMU + recent SmolVM image	vsock
Linux + Firecracker + recent SmolVM image	vsock
macOS + QEMU	SSH
Windows guest	SSH

Recent SmolVM images start the Rust guest agent before networking and sshd. That lets vsock commands run before the sandbox network is ready.

Use the Python SDK

Leave comm_channel unset for the automatic path:

from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo ready")
    print(result.stdout)

Force SSH when you want the older network path:

from smolvm import SmolVM

with SmolVM(comm_channel="ssh") as vm:
    print(vm.run("whoami").stdout)

Force vsock when you want startup to fail if the guest agent is unavailable:

from smolvm import SmolVM

with SmolVM(comm_channel="vsock") as vm:
    print(vm.run("cat /proc/uptime").stdout)

An explicit comm_channel="vsock" request is strict. If the host, backend, or guest image cannot use vsock, SmolVM raises an error instead of falling back to SSH.

Use the CLI

Open a fast shell:

smolvm sandbox shell my-vm

smolvm sandbox shell uses the vsock terminal stream when the sandbox supports it. If the fast shell feature is unavailable, it falls back to SSH for that session. Move files over the selected channel:

smolvm sandbox file upload my-vm ./report.csv /workspace/report.csv
smolvm sandbox file download my-vm /workspace/output.json ./output.json

Pick a channel for file and environment operations:

smolvm sandbox file upload my-vm ./report.csv /workspace/report.csv --comm-channel vsock
smolvm sandbox env list my-vm --comm-channel ssh

Open a real SSH session when you need SSH itself:

smolvm sandbox ssh my-vm

smolvm sandbox ssh always uses SSH. Port forwarding also uses SSH tunnels when the backend needs them.

Guest sync before snapshots

Before SmolVM pauses a sandbox for a snapshot, it asks the guest to flush filesystem state. On recent images, the guest agent exposes a dedicated /sync endpoint over vsock. This gives SmolVM a direct “save files now” operation before it captures the disk. If the guest agent is older or unavailable, SmolVM can use the raw command path as a fallback for some operations. The raw path runs the command directly in the guest instead of wrapping it in a login shell.

If snapshot creation times out before a disk artifact appears, check the control channel and guest agent first. The failure may be in guest sync, before SmolVM starts copying snapshot files.

Troubleshooting

vsock is unavailable on Linux

For QEMU, make sure the host has the vhost_vsock driver loaded:

sudo modprobe vhost_vsock
test -e /dev/vhost-vsock

For Firecracker, vsock is available on Linux through Firecracker’s host-side Unix socket bridge. If a Firecracker sandbox still uses SSH, recreate it with a recent SmolVM image so the guest agent is present.

The guest agent does not answer

Use a current published image or rebuild your custom image with the SmolVM guest agent. Published images and images built through ImageBuilder include /usr/local/bin/smolvm-guest-agent.For a one-off compatibility check, force SSH:

smolvm sandbox env list my-vm --comm-channel ssh

The fast shell falls back to SSH

This is expected when the sandbox image does not advertise terminal-stream support. smolvm sandbox shell tries the fast vsock terminal first, then opens SSH if that feature is missing.

Next steps

Runtime backends

Compare Firecracker, QEMU, and libkrun

Snapshot and restore

See how guest sync fits into snapshots

smolvm sandbox shell

Open the fast interactive shell

Troubleshooting

Fix startup and guest-agent failures

​What you can do

​Default channel selection

​Use the Python SDK

​Use the CLI

​Guest sync before snapshots

​Troubleshooting

​Next steps

Runtime backends

Snapshot and restore

smolvm sandbox shell

Troubleshooting

What you can do

Default channel selection

Use the Python SDK

Use the CLI

Guest sync before snapshots

Troubleshooting

Next steps