Rust SDK
The Rust SDK runs microVMs from a Rust program, locally or on smol cloud, through the same Machine model the Node and Python SDKs expose, with fewer of their methods: it has no method to
publish a port, and no jobs, port links or keepMachineId. For cloud routes it lacks, the crate re-exports
the cloud client as smolmachines::smol_cloud. On the local target the crate drives a smolvm engine as a child process, fetching one on its own if the host has none.
Install
The crate is named smolmachines.
cargo add smolmachines The crate needs Rust 1.82 or newer.
The local target does not need the CLI installed. crates.io serves source rather than
binaries, so on the first call that asks for a local machine the crate downloads the engine
release matching its own version and caches it; nothing is downloaded for a cloud machine. It
looks first at SMOLVM, then for the engine inside an installed smol CLI of the same minor release,
then for an installed smolvm of that minor release, at the crate’s patch or newer, and only then
downloads. Point SMOLVM at a binary to use an installed engine instead, SMOLMACHINES_CACHE_DIR to move the
cache, SMOLMACHINES_ENGINE_VERSION to pin a different engine, and SMOLMACHINES_NO_DOWNLOAD=1 to refuse the fetch, which makes a host with no engine fail rather than reach the network. The
cloud target needs none of this.
For the local target, the supported hosts are macOS on Apple Silicon and Linux x64 or arm64 with glibc 2.34 or newer, each with a hypervisor: the Hypervisor framework on macOS, KVM on Linux. The cloud target works anywhere the crate builds.
Create a local machine
use smolmachines::Machine;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let machine = Machine::builder("hello")
.image("alpine:latest")
.cpus(1)
.memory_mib(512)
.network(true)
.create()?;
machine.start()?;
let result = machine.exec(["uname", "-sm"])?;
println!("{}", result.stdout_utf8().trim());
machine.delete()?;
Ok(())
} The builder takes the machine’s name, and create() returns before the machine is started, so start() is a separate call. exec returns a result whose stdout_utf8() is the captured output.
Networking is off unless you ask for it. On the local target the crate drives the engine of its own
version, which fetches an uncached registry image on the host whenever the machine cannot reach the
registry itself, so .network(true) is for the workload rather than the image. Pin a different
engine with SMOLMACHINES_ENGINE_VERSION.
update_network(&policy) replaces a stopped local machine’s network policy with exactly the one
given (no network, every host, or an allow list that drops whatever the machine allowed before),
from its next start, and network() reads the policy back. It is local only: no Rust method changes
a cloud machine’s network, so send PUT /v1/machines/{id}/network as Change a machine after create shows. The Rust Machine has no method to publish a port either; the crate re-exports the cloud
client as smolmachines::smol_cloud, whose blocking::Client::set_ports(id, &[8080, 3000]) replaces a cloud machine’s ports with the guest ports given. smolmachines::engine_cli() returns the path of the engine binary the crate drives, for
a program that runs smolvm machine exec -t in its own terminal while the SDK manages the machine.
Choose local or cloud
The default is local. Only an explicit credential moves that, either api_key on ConnectOptions or SMOL_CLOUD_TOKEN in the environment, so a smol auth login session on disk
never silently redirects a program that meant to run locally.
use smolmachines::{ConnectOptions, Machine};
// Local: the crate drives the engine as a child process.
let local = Machine::builder("here").image("alpine:latest").create()?;
// Cloud: the control plane runs it. create_with also starts the machine and
// waits for its agent, so it is ready to work when this returns.
let remote = Machine::builder("there")
.image("alpine:latest")
.auto_stop_seconds(300)
.create_with(&ConnectOptions::cloud())?; create_with on the cloud target starts the machine and waits for its agent, so unlike the local
path it does not need a separate start().
Machine::connect on a stopped local machine returns an error at once rather than starting it. ConnectOptions::local().start_if_stopped() with connect_with starts it, or resumes a paused
one, as part of connecting; a cloud connect never starts anything. copy_in and copy_out move a
file, or with copy_in a directory as cp -r does, between the host and a running local machine.
Which SDK to reach for
| You are writing | Package | Page |
|---|---|---|
| Rust | smolmachines on crates.io | this page |
| TypeScript or JavaScript | smolmachines on npm | SDK Quick Start |
| Python | smolmachines on PyPI | SDK Quick Start |
| Go | github.com/smol-machines/smol/sdk/go | SDK Quick Start |
All four drive the same engine and the same cloud API. The Node and Python packages embed it through NAPI and pyo3, and the Go module loads it without cgo; the Rust crate drives the engine as a child process and fetches it when the host has none.
See Machine API for the method surface they share, and Use SDK on Cloud for the cloud target’s configuration fields.