ol.smolvm

Clojure bindings for local microVMs and smol cloud machines.

doc status: experimental

ol.smolvm lets JVM Clojure programs and Babashka scripts run guest commands, transfer files, stream output, and manage smol machines. Use ol.smolvm for local microVMs or ol.smolvm.cloud for the smol cloud HTTP API.

Local execution needs a native runtime and hardware virtualization. smol cloud operations use an API token and need no local hypervisor.

Project status: Experimental.

This SDK is unreleased. Use a source checkout.

Quick Start

Run uname -a in a temporary Alpine machine with outbound networking:

(require '[ol.smolvm :as smol])
;; => nil

(smol/initialize)
;; => {:version "1.32.4", :platform "linux-x64", :abi-version 1}

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

(with-open [machine (smol/create {:name "readme-example"
                                 :network? true
                                 :image "alpine"})]
  (print (:stdout (smol/exec machine ["uname" "-a"]))))
;; prints: Linux readme-example 6.18.55 ... x86_64 Linux
;; => nil

Closing this handle deletes the machine and its storage, including when execution throws.

Installation

For local execution on Linux x86-64, use Nix with flakes enabled and a host with access to /dev/kvm. Clone the SDK and enter its development shell:

git clone https://github.com/outskirtslabs/smolvm-clj.git
cd smolvm-clj
nix develop

Build the pinned runtime companion JAR and start a Clojure REPL:

bb native:jars :platforms '["linux-x64"]'
clojure -J-Xss4m -J--enable-native-access=ALL-UNNAMED \
  -J-Dbabashka.json.provider=org.clojure/data.json \
  -Sdeps '{:paths ["src" "resources" "target/smol-native-linux-x64-1.32.4.jar"]}' -M

See installation for Babashka, other supported hosts, and setup for smol cloud.

Documentation

Licensing

The Clojure code uses EUPL-1.2. Native runtime bundles include separate upstream licenses and notices.