# bsdkrun_ex v0.3.1 - Table of Contents

> Elixir SDK for bsdkrun — a Firecracker-style microVM launcher for BSD, Linux, and unikernel guests.

## Pages

- [bsdkrun_ex (Elixir SDK)](readme.md)

## Modules

- [Bsdkrun](Bsdkrun.md): Elixir SDK for [**bsdkrun**](https://github.com/tsirysndr/bsdkrun) — a
Firecracker-style microVM launcher for **BSD and Linux** guests on macOS and
Linux, built on [libkrun](https://github.com/containers/libkrun).
- [Bsdkrun.Args](Bsdkrun.Args.md): 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.
- [Bsdkrun.Binary](Bsdkrun.Binary.md): Resolves the `bsdkrun` binary. First match wins; the result is cached in
`:persistent_term`. Resolution order
- [Bsdkrun.Cli](Bsdkrun.Cli.md): Shells out to the `bsdkrun` binary via `System.cmd/3`.
- [Bsdkrun.Client](Bsdkrun.Client.md): 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`.
- [Bsdkrun.Client.Shell](Bsdkrun.Client.Shell.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`.

- [Bsdkrun.Client.Subscription](Bsdkrun.Client.Subscription.md): A handle to a live GraphQL subscription — returned by
`Bsdkrun.Client.subscribe/4` and `Bsdkrun.Client.follow_logs/3`.

- [Bsdkrun.GraphQL](Bsdkrun.GraphQL.md): The HTTP transport for `Bsdkrun.Client`: one `POST` per query or mutation,
over Erlang's built-in `:httpc` (part of `:inets` — no hex dependency).
- [Bsdkrun.GraphQLSocket](Bsdkrun.GraphQLSocket.md): 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`.
- [Bsdkrun.Images](Bsdkrun.Images.md): Image operations: list downloaded OCI + fetched BSD images.
- [Bsdkrun.Networks](Bsdkrun.Networks.md): 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).
- [Bsdkrun.Sandbox](Bsdkrun.Sandbox.md): A handle to a running (or stopped) `bsdkrun` microVM. Create one with
`create/1`, reconnect with `get/1`, or enumerate with `list/1`.
- [Bsdkrun.Sandbox.Builder](Bsdkrun.Sandbox.Builder.md): 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"
- [Bsdkrun.System](Bsdkrun.System.md): Host-level toolchain + image operations.
- [Bsdkrun.Types](Bsdkrun.Types.md): Typed structs mirroring `bsdkrun`'s JSON output, plus mapping helpers that
turn a decoded `--json` row (string keys) into the corresponding struct.

- [Bsdkrun.Types.CommandResult](Bsdkrun.Types.CommandResult.md): 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`.

- [Bsdkrun.Types.ImageInfo](Bsdkrun.Types.ImageInfo.md): An image as reported by `bsdkrun images --json`.
- [Bsdkrun.Types.NetworkInfo](Bsdkrun.Types.NetworkInfo.md): A global network as reported by `bsdkrun network ls --json`.
- [Bsdkrun.Types.PortForward](Bsdkrun.Types.PortForward.md): A host->guest TCP port forward, as reported by `bsdkrun ps --json`.
- [Bsdkrun.Types.Result](Bsdkrun.Types.Result.md): The captured result of running a command in the guest (`Bsdkrun.Sandbox.exec/3`).

- [Bsdkrun.Types.SandboxInfo](Bsdkrun.Types.SandboxInfo.md): A machine as reported by `bsdkrun ps --json`.
- [Bsdkrun.Types.ShellSessionInfo](Bsdkrun.Types.ShellSessionInfo.md): A shell/exec session opened via the GraphQL `openShell` mutation.
- [Bsdkrun.Types.VolumeInfo](Bsdkrun.Types.VolumeInfo.md): A volume as reported by `bsdkrun volume ls --json`.
- [Bsdkrun.Volumes](Bsdkrun.Volumes.md): Persistent volume operations.
- [Bsdkrun.WsFrame](Bsdkrun.WsFrame.md): 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.

- Exceptions
  - [Bsdkrun.Error](Bsdkrun.Error.md): The single exception type raised (or returned in `{:error, _}` tuples) by the
SDK. `kind` discriminates the failure

