> ## 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.

# Control channel

> How SmolVM runs commands, copies files, and opens shells inside a sandbox over SSH or the faster vsock guest-agent channel.

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 |

<Tooltip tip="vsock is a socket connection built into the virtual machine. It lets the host and guest talk without opening a TCP port.">
  vsock
</Tooltip>

## Default channel selection

SmolVM resolves the channel in this order:

1. **Explicit request** - `SmolVM(comm_channel="ssh")` or `SmolVM(comm_channel="vsock")`
2. **Saved VM config** - a channel stored with the sandbox
3. **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               |

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

## Use the Python SDK

Leave `comm_channel` unset for the automatic path:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
from smolvm import SmolVM

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

<Warning>
  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.
</Warning>

## Use the CLI

Open a fast shell:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

<Tip>
  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.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="vsock is unavailable on Linux">
    For QEMU, make sure the host has the `vhost_vsock` driver loaded:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    smolvm sandbox env list my-vm --comm-channel ssh
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Runtime backends" icon="microchip" href="/smolvm/concepts/backends">
    Compare Firecracker, QEMU, and libkrun
  </Card>

  <Card title="Snapshot and restore" icon="camera" href="/smolvm/features/snapshots">
    See how guest sync fits into snapshots
  </Card>

  <Card title="smolvm sandbox shell" icon="terminal" href="/smolvm/cli/shell">
    Open the fast interactive shell
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/smolvm/advanced/troubleshooting">
    Fix startup and guest-agent failures
  </Card>
</CardGroup>