# ol.smolvm

> Clojure bindings for local microVMs and [smol cloud](https://smolmachines.com/) machines.

![doc](https://img.shields.io/badge/doc-outskirtslabs-orange.svg)
![status: experimental](https://img.shields.io/badge/status-experimental-orange.svg)

`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](https://smolmachines.com/) HTTP API.

Local execution needs a native runtime and hardware virtualization.
[smol cloud](https://smolmachines.com/) operations use an API token and need no local hypervisor.

Project status: **[Experimental](https://docs.outskirtslabs.com/open-source-vital-signs#experimental)**.

This SDK is unreleased. Use a source checkout.

## Quick Start

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

```clojure
(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:

```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:

```shell
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](https://docs.outskirtslabs.com/ol.smolvm/next/installation)
for Babashka, other supported hosts, and setup for [smol cloud](https://smolmachines.com/).

## Documentation

* [Docs](https://docs.outskirtslabs.com/ol.smolvm/next/)
* [API Reference](https://docs.outskirtslabs.com/ol.smolvm/next/api)
* [Support via GitHub Issues](https://github.com/outskirtslabs/smolvm-clj/issues)

## Licensing

The Clojure code uses [EUPL-1.2](https://spdx.org/licenses/EUPL-1.2.html).
Native runtime bundles include separate upstream licenses and notices.