# How to install the SDK

The SDK supports local microVMs and [smol cloud](https://smolmachines.com/).
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](https://clojars.org/com.outskirtslabs/smolvm-clj).

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

```clojure
{: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.

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

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

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

```clojure
(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](cloud-commands.adoc).

## 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.