Use SDK in Local

The local target runs a microVM through the engine embedded in the smolmachines package. Select target: "local" explicitly when an environment may also contain cloud credentials.

Platform requirements

The prebuilt local SDK supports:

• macOS 11 or later on Apple Silicon
• Linux x86_64 or arm64 with glibc 2.34 or later
• Linux kernel 5.4 or later, with access to /dev/kvm

Common supported Linux distributions include Ubuntu 22.04+, Debian 12, RHEL 9, and Amazon Linux 2023.

The local SDK is not currently prebuilt for Intel Macs, native Windows, or Linux systems using glibc earlier than 2.34. Use the cloud target from those hosts.

Check Linux KVM access with:

ls -la /dev/kvm

If your user lacks access, add it to the kvm group and start a new login session:

sudo usermod -aG kvm "$USER"

No separate engine install

The npm package and Python wheel include the local runtime libraries, boot helper, and guest root filesystem. You do not need to:

• Install the smolvm CLI
• Run smolvm serve
• Start a background daemon

Machine.create() boots the embedded engine in process.

Select local explicitly

import { Machine } from "smolmachines";

const machine = await Machine.create(
  { resources: { cpus: 2, memoryMb: 1024 } },
  { target: "local" },
);

from smol import ConnectOptions, Machine, MachineConfig, ResourceSpec

machine = Machine.create(
    MachineConfig(resources=ResourceSpec(cpus=2, memory_mb=1024)),
    ConnectOptions(target="local"),
)

Run an OCI image

Use run(image, command) to pull an OCI image and run a command in it:

const result = await machine.run(
  "node:22-alpine",
  ["node", "-e", "console.log(process.version)"],
);
result.assertSuccess();

result = machine.run(
    "python:3.12-alpine",
    ["python", "-c", "import sys; print(sys.version)"],
)
result.assert_success()

Image pulls happen outside the guest. Enable resources.network only when the guest workload needs DNS or outbound network access; guest networking is off by default.

Mount a host directory

Local machines can bind an absolute host path into the guest. Mounts are writable by default.

const machine = await Machine.create(
  {
    mounts: [
      {
        source: "/absolute/path/to/project",
        target: "/workspace",
        readOnly: true,
      },
    ],
  },
  { target: "local" },
);

from smol import MachineConfig, MountSpec

config = MachineConfig(
    mounts=[
        MountSpec(
            source="/absolute/path/to/project",
            target="/workspace",
            read_only=True,
        )
    ]
)

Only mount paths the workload needs. Code in the machine can read or modify every writable path you expose.

Mounting a host directory at /workspace replaces the machine’s default storage-disk workspace for that path. Files written through a writable mount are created on the host with the ownership produced by the guest process, which may be root. Prefer a dedicated directory and a read-only mount when the workload does not need to modify it.

Local-only methods

These methods apply to the local target:

• run() pulls an image and executes a command in it
• pullImage() / pull_image() caches an OCI image
• listImages() / list_images() lists cached images

endpoint() and the public url() workflow require the cloud control plane. For a local service, publish a host-to-guest port with PortSpec and connect to the host port directly.

See Machine API for configuration and lifecycle methods.