Installation

The smol SDK (smolmachines) embeds isolated microVM sandboxes directly in your Node or Python code — the engine runs in-process, so there is no server to start. The same API runs locally or against the smolfleet cloud. The standalone smol CLI is optional and installed separately.

SDK

TypeScript / JavaScript

npm install smolmachines

Requires Node.js 18.0.0 or later.

import { Machine } from 'smolmachines';

Python

pip install smolmachines

Requires Python 3.9 or later.

from smol import Machine, MachineConfig, ResourceSpec

The package is published as smolmachines on both npm and PyPI. In Python you import it from the smol module.

Command-Line Tool (optional)

The SDK needs no CLI. If you also want the standalone smol CLI — create / run / exec machines, pack portable .smolmachine artifacts, push to the container registry, and deploy to the cloud — install the self-contained bundle:

curl -sSL https://raw.githubusercontent.com/smol-machines/smol/main/scripts/install.sh | bash

The bundle carries its own runtime + guest agent, extracts to ~/.smol, and symlinks smol onto your PATH (~/.local/bin). There is no separate engine to install. Verify it:

smol run python:3.12-alpine -- python -c "print(2 ** 10)"   # → 1024

Platform Requirements

The native (local) path runs on:

macOS

• macOS 11.0 (Big Sur) or later
• Apple Silicon (M1/M2/M3)

Linux

• x64 or arm64 with glibc ≥ 2.34 (RHEL 9, Ubuntu 22.04+, Debian 12, Amazon Linux 2023)
• Linux kernel 5.4+ with KVM support
• User must have access to /dev/kvm

# Check KVM access
ls -la /dev/kvm

# If needed, add yourself to the kvm group
sudo usermod -aG kvm $USER
# Then log out and back in

The cloud transport works anywhere the package installs. Not yet prebuilt for the local path: macOS Intel and older Linux (glibc earlier than 2.34) — use the cloud transport there.

Corporate Proxy / VPN

If your network requires a proxy, pass the proxy settings into the machine with -e:

smol run --net \
  -e https_proxy=http://proxy.corp:3128 \
  -e http_proxy=http://proxy.corp:3128 \
  -e no_proxy=localhost,127.0.0.1 \
  alpine -- wget -q -O /dev/null https://example.com

Or declare them in a Smolfile:

net = true
env = [
  "https_proxy=http://proxy.corp:3128",
  "http_proxy=http://proxy.corp:3128",
  "no_proxy=localhost,127.0.0.1"
]

The machine uses the host’s DNS server automatically, so DNS resolution works behind VPNs and corporate networks.

Verify Installation

import { Machine } from 'smolmachines';

const m = await Machine.create({ resources: { cpus: 2, memoryMb: 1024 } });
try {
  const r = await m.run('python:3.12-alpine', ['python', '-c', 'print(2 ** 10)']);
  console.log(r.stdout); // "1024\n"
} finally {
  await m.delete();
}

from smol import Machine, MachineConfig, ResourceSpec

# Context-managed: the machine is deleted automatically on exit.
with Machine.create(MachineConfig(resources=ResourceSpec(cpus=2, memory_mb=1024))) as m:
    r = m.run("python:3.12-alpine", ["python", "-c", "print(2 ** 10)"])
    print(r.stdout)  # "1024\n"