API Reference bsdkrun_ex v#0.3.2

Elixir SDK for bsdkrun — a Firecracker-style microVM launcher for BSD and Linux guests on macOS and Linux, built on libkrun.

Builds the full bsdkrun argv (minus the binary and global flags) for a detached create. Ported verbatim from the TypeScript SDK's args.ts; every path ends with -d so create yields a handle.

Resolves the bsdkrun binary. First match wins; the result is cached in :persistent_term. Resolution order

Shells out to the bsdkrun binary via System.cmd/3.

A remote client for a bsdkrund daemon's GraphQL API — talks straight to POST <url> (queries/mutations) and a graphql-transport-ws socket (subscriptions), instead of shelling out to a local bsdkrun binary like Bsdkrun.Sandbox does. Same contract the web frontend speaks (web/src/lib/graphql.ts, web/src/lib/api.ts) and the daemon documents in daemon/README.md.

A live interactive shell/exec session, opened by Bsdkrun.Client.shell/3. Output is delivered exactly as configured on shell/3 (mailbox messages by default, or the on_data callback); drive the session with write/2, resize/3 and close/1.

A handle to a live GraphQL subscription — returned by Bsdkrun.Client.subscribe/4 and Bsdkrun.Client.follow_logs/3.

The single exception type raised (or returned in {:error, _} tuples) by the SDK. kind discriminates the failure

The HTTP transport for Bsdkrun.Client: one POST per query or mutation, over Erlang's built-in :httpc (part of :inets — no hex dependency).

One shared graphql-transport-ws socket per Bsdkrun.Client "connection" (same url + token), multiplexing every live subscription over it — exec/4, shell/3, follow_logs/3 and the subscribe/4 escape hatch all share one socket per client. Started lazily on the first subscription, under Bsdkrun.Client.SocketSupervisor (a DynamicSupervisor), and registered in Bsdkrun.Client.Registry by {url, token} so every caller using the same Bsdkrun.Client finds the same socket. See the private ensure_conn/1 function in Bsdkrun.Client.

Image operations: list downloaded OCI + fetched BSD images.

Global-network operations: opt machines into a shared subnet so they get distinct IPs and reach each other by IP and by name (docker-compose style).

A handle to a running (or stopped) bsdkrun microVM. Create one with create/1, reconnect with get/1, or enumerate with list/1.

A pipe-friendly, pure builder for Bsdkrun.Sandbox.create/1's options — volumes, mounts, ports and the like are only ever bound at boot (the bsdkrun CLI has no runtime "attach" for them), so building the spec up with with_*/2 calls before create/1 is how a volume or network gets attached "by pipe"

Host-level toolchain + image operations.

Typed structs mirroring bsdkrun's JSON output, plus mapping helpers that turn a decoded --json row (string keys) into the corresponding struct.

The outcome of a daemon command run to completion, as reported by Bsdkrun.Client over GraphQL (stopMachine, removeMachines, etc.). A non-zero exit_code is a state to inspect, not necessarily a transport failure — mirrors the GraphQL schema's CommandResult.

An image as reported by bsdkrun images --json.

A global network as reported by bsdkrun network ls --json.

A host->guest TCP port forward, as reported by bsdkrun ps --json.

The captured result of running a command in the guest (Bsdkrun.Sandbox.exec/3).

A machine as reported by bsdkrun ps --json.

A shell/exec session opened via the GraphQL openShell mutation.

A volume as reported by bsdkrun volume ls --json.

Persistent volume operations.

Hand-rolled RFC 6455 WebSocket framing for Bsdkrun.GraphQLSocket: the Sec-WebSocket-Accept handshake computation, encoding a masked client frame, and decoding a frame off the front of a byte buffer.