@spec ai_agents(t()) ::
  {:ok, [Bsdkrun.Types.AiAgent.t()]} | {:error, Bsdkrun.Error.t()}

The coding agents, and whether each one's sandbox image is built.

@spec ai_remove(t(), String.t(), boolean()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Remove an agent's sandboxes, and unless keep_home its saved login too.

@spec ai_sessions(t()) ::
  {:ok, [Bsdkrun.Types.AiSession.t()]} | {:error, Bsdkrun.Error.t()}

Agent sandboxes, newest first.

@spec ai_shell_command(t(), String.t(), String.t()) ::
  {:ok, [String.t()]} | {:error, Bsdkrun.Error.t()}

The argv that starts the agent's TUI — pass it to shell/3.

@spec ai_start(t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Start (or reuse) a sandbox; returns its machine id.

Options: :cpus, :mem, :workspace (a path on the engine's host), and :new to boot a second sandbox against the same saved login.

@spec ai_stop(t(), String.t()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Stop an agent's sandboxes. Its saved login survives.

@spec branch(t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a NEW machine from a snapshot — or from a machine, which is snapshotted first — and return the new machine's id.

The state is cloned, never booted in place, so the source is untouched and one snapshot can be branched any number of times. With no :ports, the snapshot's own forwards are inherited, with any host port that is already taken swapped for a free one.

@spec commit(t(), String.t(), String.t(), String.t()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Snapshot a machine into a named flavor, like docker commit.

@spec docker_container(t(), String.t(), String.t() | [String.t()]) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Act on containers: start / stop / restart / kill / pause / unpause / rm.

@spec docker_containers(t(), boolean()) ::
  {:ok, [Bsdkrun.Types.DockerContainer.t()]} | {:error, Bsdkrun.Error.t()}

Containers in the engine. all: false lists only running ones.

@spec docker_logs(t(), String.t(), pos_integer()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

One container's logs (stdout+stderr, most recent tail lines).

@spec docker_start(
  t(),
  keyword()
) :: {:ok, Bsdkrun.Types.DockerStatus.t()} | {:error, Bsdkrun.Error.t()}

Start (or resume) the engine, returning its status once it answers.

Idempotent: the VM has a fixed name, so this resumes the existing one rather than creating a second. Options: :cpus, :mem, :mounts, :no_home, :publish_bind, :disk_size.

@spec docker_status(t()) ::
  {:ok, Bsdkrun.Types.DockerStatus.t()} | {:error, Bsdkrun.Error.t()}

Is the Docker engine up, and where is its socket?

@spec docker_stop(t()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Stop the engine. Images and containers stay on its disk.

@spec exec(t(), String.t(), String.t() | [String.t()], keyword()) ::
  {:ok, %{exit_code: integer() | nil, output: binary()}}
  | {:error, Bsdkrun.Error.t()}

Run a command to completion and collect its output. Blocks the calling process until the command exits (opts[:timeout], default 300_000ms). command is an argv list or a bare program name string. Opts: :env (a map or "K=V" list), :rows/:cols (pty size, default 24x80), :timeout.

@spec follow_logs(t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Client.Subscription.t()} | {:error, Bsdkrun.Error.t()}

Follow the machine's console log live, over the machineLogs subscription. Opts: :boot (bsdkrun's own boot log, default false), :on_data (fn subscription_id, event -> end) and :owner — see the module doc. With no :on_data, events arrive as {:bsdkrun_logs, subscription_id, event} messages, event being {:data, binary} | {:exit, exit_code} | {:error, %Bsdkrun.Error{}} | :complete.

@spec from_env() :: {:ok, t()} | {:error, Bsdkrun.Error.t()}

Build a client from BSDKRUN_URL / BSDKRUN_TOKEN. BSDKRUN_URL unset is an error; BSDKRUN_URL set without BSDKRUN_TOKEN is also an error — this never silently proceeds unauthenticated (mirrors daemon/src/client.rs's RemoteConfig::from_env for the gRPC client; different env vars, same philosophy, since a GraphQL endpoint is a different port and URL shape).

@spec from_env!() :: t()

Like from_env/0, but returns the client or raises Bsdkrun.Error.

@spec get(t(), String.t()) ::
  {:ok, Bsdkrun.Types.SandboxInfo.t() | nil} | {:error, Bsdkrun.Error.t()}

Fetch a single machine by id or name (a unique prefix is enough), or nil if there is no such machine.

@spec get!(t(), String.t()) :: Bsdkrun.Types.SandboxInfo.t() | nil

Like get/2, but returns the machine (or nil) or raises Bsdkrun.Error.

@spec list(t(), boolean()) ::
  {:ok, [Bsdkrun.Types.SandboxInfo.t()]} | {:error, Bsdkrun.Error.t()}

List machines. all: true includes exited ones (default: running only).

@spec list!(t(), boolean()) :: [Bsdkrun.Types.SandboxInfo.t()]

Like list/2, but returns the list or raises Bsdkrun.Error.

@spec logs(t(), String.t(), boolean()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Read the machine's console log as a single string, one-shot. Pass boot: true for bsdkrun's own boot log.

@spec new(keyword()) :: t()

Build a client. Does not connect — connections are made lazily, on first use.

@spec normalize_url(String.t()) :: String.t()

Normalize what a person actually pastes into the daemon's GraphQL endpoint URL: trim, default to http:// when no scheme is given, strip trailing slashes, and append /graphql unless it is already there. Mirrors web/src/lib/connection.ts's normalizeUrl.

@spec remove(t(), String.t() | [String.t()], boolean()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Remove one or more machines and their state. force: true stops them first if running.

@spec remove_snapshots(t(), String.t() | [String.t()]) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Delete snapshots and their data. Machines branched from them are unaffected.

@spec request(t(), String.t(), map()) :: {:ok, term()} | {:error, Bsdkrun.Error.t()}

Run a raw query or mutation. Returns {:ok, data} (the response's data field) or {:error, %Bsdkrun.Error{}}.

@spec restore(t(), String.t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Put a machine's disk state back to one of its snapshots.

:force (default true) stops the machine first — it holds the very files being replaced. :backup (default true) snapshots the state being overwritten, which is a CoW clone and therefore free. The machine is left stopped.

@spec rollback(t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Restore a machine to its most recent snapshot.

@spec run_bsd(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a FreeBSD/NetBSD machine. opts maps to RunBsdInput, :os being :freebsd or :netbsd.

@spec run_flavor(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a named flavor. opts maps to RunFlavorInput.

@spec run_linux(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a Linux (OCI) machine. opts maps to RunLinuxInput; see the module doc for the input shape.

@spec run_nanos(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a Nanos unikernel. opts maps to RunNanosInput. No agent — no exec/4/commit/4.

@spec run_osv(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot an OSv unikernel. opts maps to RunOsvInput. No agent — no exec/4/commit/4.

@spec run_solo5(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a Solo5 (MirageOS) unikernel. opts maps to RunSolo5Input.

Runs under the solo5-hvt tender rather than libkrun; the unikernel declares its own network and block devices in its MFT1 manifest note, so only host-side facts are taken: :path (a .hvt binary or a project dir whose dist/ holds one, default "."), :block backing files ("NAME=FILE"), and :args handed to the unikernel itself. Always a single vCPU — :cpus above 1 is warned about and ignored. No disk, no agent — no exec/4/commit/4.

@spec run_unikraft(t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, Bsdkrun.Error.t()}

Boot a Unikraft unikernel. opts maps to RunUnikraftInput. No disk, no agent — no exec/4/commit/4.

@spec shell(t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Client.Shell.t()} | {:error, Bsdkrun.Error.t()}

Open a live interactive session on a machine (or run opts[:command] if given, instead of a login shell) and return a Shell.t() handle. Output is delivered as it arrives, exactly as follow_logs/3 does: opts[:on_data] (fn session_id, event -> end) or, with no callback, {:bsdkrun_shell, session_id, event} messages to opts[:owner] (default: the caller). event is {:data, binary} | {:exit, exit_code} | {:error, _} | :complete.

@spec snapshot(t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Types.SnapshotInfo.t()} | {:error, Bsdkrun.Error.t()}

Capture a machine's disk state. :name defaults to <machine>-<n>.

A BSD guest is powered off first — a mounted UFS cannot be cloned consistently — so the machine is left stopped; start/2 brings it back.

@spec snapshots(t(), String.t() | nil) ::
  {:ok, [Bsdkrun.Types.SnapshotInfo.t()]} | {:error, Bsdkrun.Error.t()}

List snapshots, newest first. Pass a machine id/name to narrow to its own.

@spec start(t(), String.t()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Restart a stopped machine in place — same id, disk/rootfs, resources.

@spec stop(t(), String.t()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Stop the machine (BSD guests clean-poweroff; Linux is SIGTERM'd).

@spec subscribe(t(), String.t(), map(), keyword()) ::
  {:ok, Bsdkrun.Client.Subscription.t()} | {:error, Bsdkrun.Error.t()}

Start a raw subscription. opts[:on_data] (arity 2, fn id, event -> end) receives {:next, data} | {:error, %Bsdkrun.Error{}} | :complete; with no callback, the same arrives as {:bsdkrun_subscription, id, event} messages to opts[:owner] (default: the calling process). Returns a Subscription.t() — cancel it with Subscription.cancel/1.

@spec update(t(), String.t(), keyword()) ::
  {:ok, Bsdkrun.Types.CommandResult.t()} | {:error, Bsdkrun.Error.t()}

Change a machine's recorded vCPU / RAM (:cpus, :mem). Applies on next start/2.