Installation

TypeScript / JavaScript

npm install smolvm

Requires Node.js 18.0.0 or later.

Python

pip install smolvm

Requires Python 3.9 or later.

Server Setup

The SDK connects to a smolvm server. Start one locally:

# Install smolvm CLI
curl -sSL https://smolmachines.com/install.sh | sh

# Start the server
smolvm serve

By default on macOS and Linux the server listens on a Unix socket ($XDG_RUNTIME_DIR/smolvm.sock); the SDK auto-detects it. To listen on a TCP address instead, pass a listen flag: smolvm serve -l 127.0.0.1:8080.

Platform Requirements

macOS

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

Linux

• 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

Corporate Proxy / VPN

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

smolvm machine run --net \
  -e https_proxy=http://proxy.corp:3128 \
  -e http_proxy=http://proxy.corp:3128 \
  -e no_proxy=localhost,127.0.0.1 \
  --image 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 VM uses the host’s DNS server automatically, so DNS resolution works behind VPNs and corporate networks.

Verify Installation

import { SmolvmClient } from 'smolvm';

const client = new SmolvmClient();
const health = await client.health();
console.log('Server status:', health.status);

from smolvm import SmolvmClient

async def check():
    client = SmolvmClient()
    health = await client.health()
    print(f"Server status: {health.status}")