# ol.smolvm.cloud

Describe cloud operations as request maps, then send them with `invoke`.

Operation builders are pure. [`invoke`](#invoke) returns a CompletableFuture
that resolves to each operation’s documented result. Machine arguments are exact IDs.
JSON record keys become kebab-case keywords. Environment and label keys
keep their spelling. State values and timestamps are strings.

## client

```clojure
(client opts)
```

Returns validated connection configuration from `opts`.

|     |     |
| --- | --- |
| Option | Meaning |
| `:base-url` | Cloud API URL. Defaults to `https://api.smolmachines.com`. |
| `:api-key` | Required bearer token. |
| `:request-timeout-ms` | Default HTTP request timeout. Defaults to 60000. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L12-L21)

---

## invoke

```clojure
(invoke client operation)
```

Starts the HTTP request described by `operation` using `client`.

Returns a `java.util.concurrent.CompletableFuture` of the decoded result.
Use `@result` to wait, or `(deref result timeout-ms timeout-value)`
to bound the wait. The request continues after a wait timeout.
HTTP and transport failures complete the future exceptionally with ex-info
containing `:code`, plus `:status` and `:request-id` when available.
Deref wraps failures in ExecutionException. Its cause carries the error data.
Empty successful responses resolve to nil.

An operation’s `:timeout` overrides the client’s default HTTP timeout.
Use [`job-cancel`](#job-cancel) to terminate a remote job.

Additional result kinds, with the same one-request CompletableFuture contract:

exec-stream resolves to a Closeable event reader. Call stream-read to consume
its response, then close it. Cancellation before delivery closes a late body.

checkpoint-upload-part sends one raw PUT to its signed URL, without API bearer,
cookies, redirects or automatic retries. Its file section is opened during
invocation and closed on completion/failure/cancellation, including failure
before the request starts. The future resolves to nil after a successful PUT.
Cancellation cannot prove that the remote part was not stored.

Absolute storage URLs are accepted only for the checkpoint part operation,
not as a general override to authenticated API operations. All new operations
keep existing sanitized errors. File paths, signed URLs, lease tokens and
progress callback exception messages/causes are not attached to errors.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L23-L53)

---

## list

```clojure
(list)
(list opts)
```

Describes listing machines. Result: a vector of full info maps.

|     |     |
| --- | --- |
| Option | Meaning |
| `:labels` | String-to-string map. Match every label. Defaults to `{}`. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L55-L62)

---

## info

```clojure
(info id)
```

Describes fetching machine `id`. Result: its full info map.

Fields include `:id`, `:name`, `:state`, `:ready`, `:source`, `:resources`,
`:ports`, `:labels`, and `:created-at` when supplied by the server.
Returned environment values are redacted by the service.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L64-L71)

---

## create

```clojure
(create config)
```

Describes creating a machine from `config`.

Result: the server’s machine-info record, including its state.
Resource allocation defaults come from the server.

|     |     |
| --- | --- |
| Option | Meaning |
| `:image` | Required OCI image reference. |
| `:name` | Machine name. Defaults to a server-generated name. |
| `:cpus` | Positive CPU count. Maps to `resources.cpus`. |
| `:memory-mb` | Positive memory allocation. Maps to `resources.memoryMb`. |
| `:storage-gb` | Positive disk allocation. Maps to `resources.diskGb`. |
| `:env` | String-to-string workload environment. Defaults to the image environment. |
| `:workdir` | Workload working directory. Defaults to the image setting. |
| `:labels` | String-to-string metadata map. Defaults to `{}`. |
| `:ports` | Vector of guest TCP port numbers. Defaults to `[]`. Host ports are allocated by the server. |
| `:network?` | True allows outbound networking, false blocks it. Omission uses the server setting. |
| `:auto-stop-ms` | Positive idle duration before stopping. Omission uses the server setting. |
| `:ttl-ms` | Positive lifetime before deletion. Omission uses the server setting. |

Durations round up to whole seconds on the wire.

Additional options:

|     |     |
| --- | --- |
| Option | Meaning |
| `:branchable?` | Boolean, maps to `forkable`. Omission uses the service setting. |
| `:disk-durability` | `:full` or `:deferred`. Omission uses the service setting. |
| `:allowed-cidrs` | Vector of nonblank CIDR strings. Defaults to `[]`. |
| `:allowed-hosts` | Vector of nonblank host strings. Defaults to `[]`. |
| `:cache-disk` | Nonblank existing cache ID/name. Attaches its latest version at its configured mount path. Omission attaches no cache. |

Nonempty allowlists select restricted networking and cannot be combined with
`:network? false`. Empty lists use `:network?` or the service setting. The
server validates CIDR/host syntax. Create does not start or wait. For a
branchable source, separately invoke start with `{:branchable? true}`.
Cache lifetime is independent of the machine. Deleting a machine does not
request cache deletion. Cache version/slot overrides are not introduced.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L73-L113)

---

## start

```clojure
(start id)
(start id opts)
```

Describes starting machine `id` from its disks.
Result: the server’s response. HTTP timeout defaults to 30 minutes.

Adds an options arity. Existing one-argument behavior is unchanged.

|     |     |
| --- | --- |
| Option | Meaning |
| `:branchable?` | Boolean. When supplied, sends `forkable` in the start query. Omission preserves ordinary start. |

This does not wait for readiness.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L115-L127)

---

## stop

```clojure
(stop id)
```

Describes stopping machine `id` without deleting its storage.
Result: the server’s response.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L129-L133)

---

## pause

```clojure
(pause id)
```

Describes pausing machine `id` with its execution state preserved.
Result: machine info. HTTP timeout defaults to 30 minutes.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L135-L139)

---

## resume

```clojure
(resume id)
```

Describes resuming the preserved execution state of machine `id`.
Result: machine info. HTTP timeout defaults to 30 minutes.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L141-L145)

---

## delete

```clojure
(delete id)
(delete id opts)
```

Describes deleting machine `id` and its storage.

|     |     |
| --- | --- |
| Option | Meaning |
| `:include-usage?` | Return the final usage report. Defaults to false. |

Result: the usage report when requested, otherwise nil.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L147-L156)

---

## exec

```clojure
(exec id command)
(exec id command opts)
```

Describes running nonempty argv vector `command` on machine `id`.

Result: `:exit-code`, `:stdout`, `:stderr`, `:stdout-bytes`,
`:stderr-bytes`, `:stdout-truncated?`, and `:stderr-truncated?`.
The result includes server metadata such as `:machine-id`, `:duration-ms`, and `:user`.
Nonzero exit codes are results. Missing exit status is an invalid response.

Cloud text can be truncated. Byte fields decode base64 when supplied,
otherwise encode the returned text as UTF-8. Invalid base64 is an error.

|     |     |
| --- | --- |
| Option | Meaning |
| `:env` | String-to-string environment overrides. Defaults to `{}`. |
| `:workdir` | Guest working directory. Defaults to the machine setting. |
| `:stdin` | Complete UTF-8 input text. Defaults to empty input. |
| `:timeout-ms` | Positive guest timeout, rounded up to whole seconds. Omission uses the server setting. |
| `:user` | Guest user name or uid[:gid]. Verify support with [`user-check`](#user-check) before use. Defaults to the image account. |

An explicit guest timeout sets the HTTP budget to that rounded timeout
plus 30 seconds, with a minimum of 60 seconds.

Additional option:

|     |     |
| --- | --- |
| Option | Meaning |
| `:output` | `:text` or `:b64`. Omission requests the server’s default, currently both. |

Sent as the output query parameter. Older servers may ignore it. The existing
result shape and strict exit/base64 checks are unchanged. Missing text fields
become empty strings, even when byte fields contain output.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L158-L190)

---

## user-check

```clojure
(user-check id user)
```

Describes a harmless command that checks support for guest `user` on machine `id`.

Result: `user` when the server confirms the requested account.
Otherwise it throws with code NOT_SUPPORTED or the command failure.
Invoke this check before an [`exec`](#exec) that specifies `:user`.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L192-L199)

---

## file-read

```clojure
(file-read id path)
(file-read id path opts)
```

Describes reading absolute guest `path` on machine `id`.

|     |     |
| --- | --- |
| Option | Meaning |
| `:as` | `:bytes` (default) returns a byte array. `:stream` returns an InputStream for the caller to close. |

Close returned streams after use. Stream mode reads the HTTP body incrementally.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L201-L210)

---

## file-write

```clojure
(file-write id path data)
```

Describes writing `data` to absolute guest `path` on machine `id`.

Accepts a byte array, UTF-8 string, `java.io.File`, or `java.nio.file.Path`.
File and Path bodies are streamed by the HTTP client during invocation.
Uploads are limited to 100 MiB by the service.

Result: nil on success. Use [`exec`](#exec) with chmod to set permissions.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L212-L221)

---

## logs

```clojure
(logs id)
(logs id opts)
```

Describes fetching workload logs for machine `id`. Result: text.

|     |     |
| --- | --- |
| Option | Meaning |
| `:tail` | Positive number of trailing lines. Defaults to 100. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L223-L230)

---

## ports-set

```clojure
(ports-set id ports)
```

Describes replacing machine `id’s published ports with `ports`.

`ports` is a vector of guest TCP port numbers. An empty vector removes
every published port. Result: machine info with allocated host ports.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L232-L238)

---

## endpoint

```clojure
(endpoint client id port)
(endpoint client id port path)
```

Returns authenticated endpoint data for guest TCP `port` on machine `id`.

Returns `{:method :get :uri string :headers map :ws-uri string}`.
Pass this map directly to `babashka.http-client/request`.
Use `assoc` to set request options such as `:method`, `:body`, or `:as`.
This pure helper uses `client` to construct the URLs and bearer header.
The returned headers contain a credential.

Optional `path` selects a path beneath the guest service. Defaults to root.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L240-L251)

---

## job-start

```clojure
(job-start id command)
(job-start id command opts)
```

Describes starting a background job with argv vector `command` on machine `id`.

Result: job info with `:id`, `:machine-id`, `:command`,
`:state`, and `:created-at`. Job states are running, exited, or lost.
Without `:user`, the job runs as the image’s configured account.

|     |     |
| --- | --- |
| Option | Meaning |
| `:env` | String-to-string environment overrides. Defaults to `{}`. |
| `:workdir` | Guest working directory. Defaults to the machine setting. |
| `:timeout-ms` | Positive runtime limit, rounded up to whole seconds. Omission allows unlimited runtime. |

Guest timeout sends SIGTERM, normally producing exit code 143.

Additional option:

|     |     |
| --- | --- |
| Option | Meaning |
| `:user` | Nonblank guest account. Omission uses the image account. |

Invoke user-check separately before use. Job replies do not prove user support.
Existing timeout rounding and other options are unchanged.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L253-L277)

---

## job-list

```clojure
(job-list id)
```

Describes listing jobs on machine `id`. Result: a vector of job-info maps.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L279-L282)

---

## job-info

```clojure
(job-info id job-id)
(job-info id job-id opts)
```

Describes fetching `job-id` on machine `id`.

Result: job info, including `:exit-code` and `:finished-at`
when available. `:stdout-bytes` and `:stderr-bytes` are byte counts.
A lost job’s machine stopped or restarted while the job was running.

|     |     |
| --- | --- |
| Option | Meaning |
| `:wait-seconds` | Long-poll until the job ends, up to 30 seconds. Defaults to 0. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L284-L295)

---

## job-output

```clojure
(job-output id job-id)
(job-output id job-id opts)
```

Describes fetching a slice of `job-id` output on machine `id`.

Result: `{:stream string :offset n :next-offset n :data bytes :eof boolean}`.
Data decodes base64 when supplied, otherwise encodes returned text as UTF-8.
EOF means the job has finished and this slice reaches the end of the stream.

|     |     |
| --- | --- |
| Option | Meaning |
| `:stream` | `:stdout` (default) or `:stderr`. |
| `:offset` | Nonnegative byte offset. Defaults to 0. |
| `:wait-seconds` | Long-poll for output or job completion, up to 30 seconds. Defaults to 0. |
| `:limit` | Positive byte limit, at most 1048576. Defaults to the server setting, currently 262144. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L297-L311)

---

## job-cancel

```clojure
(job-cancel id job-id)
```

Describes sending SIGTERM to `job-id` on machine `id`.
Result: job info. A terminated job normally exits with code 143.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L313-L317)

---

## usage

```clojure
(usage id)
```

Describes fetching the usage report for machine `id`.

Result: `{:machine-id string :from string :to string :usage map :cost map}`.
Usage includes `:total-uptime-seconds`, `:cpu-hours`, `:memory-gb-hours`,
`:disk-gb-hours`, and `:egress-gb`. Costs are integer micro-dollars,
including `:total-micros` and `:amount-due-micros`.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L319-L327)

---

## branch

```clojure
(branch id name)
(branch id name opts)
```

Describes creating child `name` from branchable source `id`.
Result: child machine info. Name is nonblank. No readiness wait or legacy-route
fallback is performed. The source can briefly pause during branching.

|     |     |
| --- | --- |
| Option | Meaning |
| `:ports` | TCP maps with required guest 1..65535 and host 0..65535. Defaults to `[]`. Host zero requests allocation. |
| `:branchable?` | Boolean, defaults to false. Requests a branchable child. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L329-L339)

---

## branch-batch

```clojure
(branch-batch id names)
(branch-batch id names opts)
```

Describes one transactional branch batch from source `id`.
Names are a nonempty vector of distinct nonblank strings. Result: a vector of
child info maps in service order. No waits or legacy-route fallback occur.

|     |     |
| --- | --- |
| Option | Meaning |
| `:ports` | TCP mappings as in branch. Defaults to `[]`. Multiple children require host zero. |

Branchable-child, count and name-prefix selectors are not provided.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L341-L352)

---

## checkpoint

```clojure
(checkpoint id)
```

Describes capturing machine `id`. Result: durable checkpoint metadata.
HTTP timeout defaults to 30 minutes. No download occurs. Download URLs are
sensitive. Local destination/store options do not apply.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L354-L359)

---

## checkpoints

```clojure
(checkpoints id)
```

Describes listing machine `id’s checkpoints. Result: a vector of metadata maps.
Download URLs can be sensitive.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L361-L365)

---

## checkpoint-restore

```clojure
(checkpoint-restore checkpoint-id name)
(checkpoint-restore checkpoint-id name opts)
```

Describes restoring durable `checkpoint-id` to new machine `name`.
Result: machine info. Both arguments are nonblank. No file upload, start or wait.

|     |     |
| --- | --- |
| Option | Meaning |
| `:egress-policy` | Map with required boolean network? and optional nonblank string vectors allowed-cidrs/allowed-hosts. Nonempty lists require true. Supplying either list with network true selects allowlist mode, even if empty. Omission of policy means blocked networking. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L367-L375)

---

## checkpoint-upload-create

```clojure
(checkpoint-upload-create size-bytes)
```

Describes allocating an upload of positive `size-bytes`.
Result: a map with checkpoint metadata, positive :part-size-bytes and a vector
of :upload-urls. URLs authorize raw storage PUTs and must not be logged.
This does not stat/read a file, transfer parts or complete the upload.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L377-L383)

---

## checkpoint-upload-part

```clojure
(checkpoint-upload-part upload-url file opts)
```

Describes one raw PUT of a file section to presigned HTTPS `upload-url`.

`file` is a nonblank path string, File or Path. Construction performs no file
I/O. The URL cannot contain user info or a fragment. Result: nil on HTTP 2xx.
No API authorization, cookies, redirects or retries. URL query bytes are kept.

|     |     |
| --- | --- |
| Option | Meaning |
| `:offset` | Required nonnegative byte offset. |
| `:length` | Required positive byte count. Offset plus length must fit a long. |
| `:timeout-ms` | Positive HTTP budget. Omission uses the client request timeout. |
| `:progress` | Optional function called with bytes read for this attempt and section length after each positive read. |

Invoke opens a fresh file section, checks that it fits a regular file, sends
exactly its declared Content-Length and closes its stream on every outcome.
Keep the file unchanged until completion. No caller-supplied InputStream is
accepted. A new invocation opens a fresh section and starts its count at zero.
Progress measures sender reads, not storage acknowledgements. Callbacks can
reach length before the HTTP outcome is known. Calls are serialized within
one PUT, not across different invocations. Callback failure fails the request
with PROGRESS_FAILED. Source file errors use FILE_ERROR. No upload plan,
part scheduling, retry/reset policy or aggregate progress is implemented here.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L385-L409)

---

## checkpoint-upload-complete

```clojure
(checkpoint-upload-complete checkpoint-id)
```

Describes completing `checkpoint-id` after every part PUT succeeded.
Result: checkpoint metadata. HTTP timeout defaults to 30 minutes. Sends no
ETag list. Does not transfer parts, retry or delete a failed upload.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L411-L416)

---

## checkpoint-delete

```clojure
(checkpoint-delete checkpoint-id)
```

Describes deleting durable `checkpoint-id` and its stored artifact. Result: nil.
The service can return HTTP 409 while referenced. Incomplete-upload abort
semantics are not established. This endpoint is a service-docs addition to Go.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L418-L423)

---

## share

```clojure
(share id)
```

Describes creating/retrieving a sharing link for machine `id`.
Result: share metadata. URL/token are credentials. Revoke with unshare.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L425-L429)

---

## unshare

```clojure
(unshare id)
```

Describes revoking machine `id’s sharing link. Result: nil.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L431-L434)

---

## port-links

```clojure
(port-links id)
```

Describes creating public port links for machine `id`.
Result: integer guest-port to URL map. URLs are credentials. This changes
access, unlike endpoint. Revoke all links with port-links-revoke.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L436-L441)

---

## port-links-revoke

```clojure
(port-links-revoke id)
```

Describes revoking every public port link for machine `id`. Result: nil.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L443-L446)

---

## assign

```clojure
(assign id opts)
```

Describes leasing a provisioned child from source machine `id`.
Result: machine-id, secret owner-token and optional machine info. No client
wait, heartbeat scheduling or cleanup. Repeated lease IDs use service
idempotency, not a retry performed by invoke.

|     |     |
| --- | --- |
| Option | Meaning |
| `:lease-id` | Required nonblank idempotency key. |
| `:task` | Optional JSON value staged at /run/smol-task.json. |
| `:files` | Optional absolute guest path to byte-array/UTF-8-string map, sent as base64. |
| `:secrets` | Optional string-to-string map. |
| `:ports` | Optional TCP mappings as in branch. |
| `:ttl-ms` | Positive lease duration rounded up to seconds. Omission uses service default. |
| `:heartbeat-ms` | Positive heartbeat duration rounded up to seconds. Omission uses service default. |

Task/result map keys keep their spelling. Do not log task/files/secrets/token.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L448-L466)

---

## lease-heartbeat

```clojure
(lease-heartbeat lease-id owner-token)
```

Describes renewing `lease-id` with secret `owner-token`. Result: nil.
Arguments are nonblank. No future heartbeat is scheduled.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L468-L472)

---

## lease-complete

```clojure
(lease-complete lease-id owner-token opts)
```

Describes completing `lease-id` with secret `owner-token`. Result: nil.
Completion can trigger child cleanup. Verify resource state separately.

|     |     |
| --- | --- |
| Option | Meaning |
| `:reason` | Required nonblank completion reason. |
| `:score` | Optional finite number. |
| `:result` | Optional JSON value, preserving payload map keys. |

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L474-L484)

---

## lease-info

```clojure
(lease-info lease-id)
```

Describes fetching `lease-id`. Result: full lease status map.
Payload fields can contain sensitive task data.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L486-L490)

---

## artifact-export

```clojure
(artifact-export id)
```

Describes exporting stopped machine `id`. Result: service metadata map.
HTTP timeout defaults to 30 minutes. This can create durable data with no
established cleanup operation. Confirm retention/cleanup before invocation.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L492-L497)

---

## cache-disk-create

```clojure
(cache-disk-create name)
(cache-disk-create name opts)
```

Describes creating cache `name`. Result: cache metadata.
Name uses lowercase ASCII letters, digits, dots, underscores or hyphens.
Requires a supporting plan. Cache storage has a separate lifetime from machines.

|     |     |
| --- | --- |
| Option | Meaning |
| `:size-gb` | Integer 1..500. Omission uses service default 20. |
| `:mount-path` | Absolute guest directory. Omission uses /cache. |

This is a pinned Node/service-docs addition to Go.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L499-L511)

---

## cache-disk-info

```clojure
(cache-disk-info id-or-name)
```

Describes fetching cache `id-or-name`. Result: cache metadata and versions.
Useful for version inspection and NOT_FOUND verification after deletion.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L513-L517)

---

## cache-disk-publish

```clojure
(cache-disk-publish id)
```

Describes publishing the configured cache of stopped machine `id`.
Result: cache and newly published version metadata. Timeout is 30 minutes.
Appends a version. Does not configure or create the cache resource.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L519-L524)

---

## cache-disk-delete

```clojure
(cache-disk-delete id-or-name)
```

Describes deleting cache `id-or-name` and ALL versions. Result: nil.
The service refuses deletion while used by a running machine. This does not
target one version. Confirm no other workload needs this shared resource.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L526-L531)

---

## exec-background

```clojure
(exec-background id command)
(exec-background id command opts)
```

Describes launching detached argv `command` on machine `id`.
Result includes positive pid parsed from stdout pid=<n>, stdout/stderr and
byte fields plus service metadata. Missing PID is INVALID_REPLY. No exit
status is synthesized. A launcher status is not remote child completion.

|     |     |
| --- | --- |
| Option | Meaning |
| `:env` | String-to-string overrides, default {}. |
| `:workdir` | Nonblank guest directory, default machine setting. |
| `:user` | Nonblank guest account. Invoke user-check first. Reply echo is checked. |

Uses client HTTP timeout. Supplied stdin, guest timeout, background, stream or
output flags fail NOT_SUPPORTED. This is not a cancellable job.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L533-L548)

---

## exec-stream

```clojure
(exec-stream id command)
(exec-stream id command opts)
```

Describes SSE execution of argv `command` on machine `id`.
Result through invoke: a Closeable event reader. Close it after use. Uses
pinned /exec/stream, no route fallback, and requires text/event-stream.

|     |     |
| --- | --- |
| Option | Meaning |
| `:env` | String-to-string overrides, default {}. |
| `:workdir` | Nonblank guest directory, default machine setting. |
| `:stdin` | Complete UTF-8 input text, default empty. |
| `:timeout-ms` | Positive guest timeout rounded up to seconds, default service setting. |
| `:user` | Nonblank account. Invoke user-check first. SSE cannot confirm account. |

Header timeout follows exec’s budget, not a timeout on later body reads.
Background/output flags are unsupported. No reconnect, replay or event queue.
Closing the reader does not promise remote command termination.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L550-L567)

---

## stream-read

```clojure
(stream-read stream)
```

Consumes one event from an already-open cloud exec `stream`, blocking as needed.
Does not submit another HTTP request. Returns stdout/stderr events with :kind
and UTF-8 :data bytes, exit with integer :exit-code, or error with :message.
Multiple SSE data lines join with newline. This is text, not binary-exact output.

Exit/error is terminal and closes the body before return. Later reads or reads
after explicit close return nil. CRLF, fragmented UTF-8 and an unterminated
final event are supported. Comments and unrecognized events are ignored.
Invalid UTF-8/exit JSON or EOF without a terminal event throws INVALID_REPLY.
A frame above 1 MiB raw wire bytes, including ignored lines/line endings,
throws LIMIT_EXCEEDED. Enforce bounds while accumulating each line.
Read/parse errors close the body. Transport errors are sanitized. Service
error-event text can contain sensitive data and is never logged by the SDK.
Use one reader thread. Close from another thread releases a blocked read,
returning nil if closure caused the failure. Interruption alone is not a
guaranteed way to stop body reads.

[source,window=_blank](https://github.com/outskirtslabs/smolvm-clj/blob/main/src/ol/smolvm/cloud.clj#L569-L587)