How to install the SDK

The SDK supports local microVMs and smol cloud. Both use the com.outskirtslabs/smolvm-clj library from Clojars. Local execution also needs native binaries for your host. Access to smol cloud uses HTTP and needs no native binaries.

Add dependencies to deps.edn for Clojure or bb.edn for Babashka. Replace SDK_VERSION in the examples with the SDK version you want from Clojars.

Use local machines

Local machines run on your computer through the smol native runtime. We do not build that runtime. We redistribute upstream release binaries in platform-specific companion JARs, with their upstream licences and notices. You do not need to compile Rust code or install the smol CLI.

Add the main library and the companion for your host. For Linux x86-64:

{:deps {com.outskirtslabs/smolvm-clj
        {:mvn/version "SDK_VERSION"}
        com.outskirtslabs/smolvm-clj-native-linux-x64
        {:mvn/version "1.32.4"}}}

The companion version follows the upstream runtime, not the Clojure library. This SDK uses runtime 1.32.4. Choose the companion that matches your host:

Host Coordinate

Linux x86-64

com.outskirtslabs/smolvm-clj-native-linux-x64

Linux ARM64

com.outskirtslabs/smolvm-clj-native-linux-arm64

macOS Apple Silicon

com.outskirtslabs/smolvm-clj-native-darwin-arm64

When you call initialize, the SDK finds the companion on the classpath, verifies their checksums and extracts them to a private temporary directory. Normal process exit removes these files. Forced termination can leave the directory on disk.

The SDK does not download binaries at runtime. The companion supplies the native library, VM executable, guest root filesystem and supporting files.

(require '[ol.smolvm :as smol])

(smol/initialize)
(smol/check-host)
;; => nil

A nil host check means the host can run local machines. Otherwise, the result includes a :code and :reason describing the problem. The native binaries do not replace the host’s virtualization support. Linux needs glibc 2.34 or later, hardware virtualization and access to /dev/kvm. macOS uses system virtualization. Local execution is not supported on Windows or Intel macOS.

Supply a runtime directory instead

Use :runtime-dir if you manage the native files separately, for example when packaging an application or preparing an offline installation. Keep the main SDK dependency, but omit the companion JAR. Unpack the upstream runtime 1.32.4 bundle for your host and pass its directory to initialize:

(smol/initialize {:runtime-dir "/absolute/path/to/runtime"})

The path must point to the complete unpacked bundle, not just its shared library (libsmol_go.so on Linux or libsmol_go.dylib on macOS). Include the guest root filesystem and supporting files. Keep smol-vmm executable and the bundle’s file layout intact. Use this call instead of the no-argument initialize above. Once a process has initialized a runtime, restart it before selecting a different directory.

Use smol cloud

For smol cloud, install only the main library:

{:deps {com.outskirtslabs/smolvm-clj {:mvn/version "SDK_VERSION"}}}

The ol.smolvm.cloud namespace sends HTTP requests to the service. It does not load the local runtime, so you need neither a companion JAR nor hardware virtualization. Do not call ol.smolvm/initialize for cloud use.

Set SMOL_API_KEY to your API token before starting the process, then create a client:

(require '[ol.smolvm.cloud :as cloud])

(def client
  (cloud/client {:api-key (System/getenv "SMOL_API_KEY")}))

Keep the token out of source files and logs. Continue with How to run smol cloud commands.

Configure Clojure or Babashka

On the JVM, select the JSON provider with -Dbabashka.json.provider=org.clojure/data.json. Local execution also requires Java 25 or later and --enable-native-access=ALL-UNNAMED. Set -Xss4m for a four-MiB thread stack. The pinned native checkpoint code exceeds a one-MiB stack and can crash the JVM. Pass these as -J options with the Clojure CLI, for example -J-Xss4m. These are JVM options, not SDK options.

For Babashka, use version 1.13.225 or later. Local execution needs an FFI-enabled build. On Linux, use a dynamic build. Babashka uses its built-in Cheshire JSON implementation and needs none of the JVM options above. The same companion JAR or runtime-directory choices apply to local execution.