bsdkrun/types

Typed records mirroring bsdkrun’s --json output, their decoders, and the result of running a command inside a guest.

The same records also back bsdkrun/client (the remote GraphQL client): sandbox_info_from_graphql and command_result_from_graphql decode the daemon’s camelCase GraphQL responses into these exact same SandboxInfo / CommandResult types, so code written against the local, CLI-shelling API and code written against a remote daemon see identical shapes.

Types

AiAgent

</>

A coding agent bsdkrun can sandbox.

Each runs in a disposable microVM with a persistent login, a shared skills store, and only the folder you choose to share.

pub type AiAgent {
  AiAgent(
    id: String,
    label: String,
    flavor: String,
    description: String,
    installed: Bool,
    running: Int,
  )
}

Constructors

AiAgent(
  id: String,
  label: String,
  flavor: String,
  description: String,
  installed: Bool,
  running: Int,
)

Arguments

flavor: The catalog flavor that installs it.
installed: Its flavor is provisioned, so a sandbox boots in a second.

AiSession

</>

One agent sandbox. It is a machine, so logs/stop work on id.

pub type AiSession {
  AiSession(
    id: String,
    name: String,
    agent: String,
    running: Bool,
    workspace: option.Option(String),
    created_at: Int,
  )
}

Constructors

AiSession(
  id: String,
  name: String,
  agent: String,
  running: Bool,
  workspace: option.Option(String),
  created_at: Int,
)

Arguments

workspace: The directory shared into it, on the engine’s host.

CacheEntry

</>

A stored cache entry, as reported by bsdkrun cache ls --json.

pub type CacheEntry {
  CacheEntry(
    key: String,
    path: String,
    compression: String,
    size: Int,
    created: Int,
    digest: String,
  )
}

Constructors

CacheEntry(
  key: String,
  path: String,
  compression: String,
  size: Int,
  created: Int,
  digest: String,
)

CommandResult

</>

The captured result of running a command in a guest.

pub type CommandResult {
  CommandResult(
    stdout: String,
    stderr: String,
    exit_code: Int,
    command: String,
  )
}

Constructors

CommandResult(
  stdout: String,
  stderr: String,
  exit_code: Int,
  command: String,
)

DockerContainer

</>

A container in the Docker engine VM — a trimmed docker ps row.

pub type DockerContainer {
  DockerContainer(
    id: String,
    name: String,
    image: String,
    command: String,
    state: String,
    status: String,
    ports: List(String),
    created: Int,
  )
}

Constructors

DockerContainer(
  id: String,
  name: String,
  image: String,
  command: String,
  state: String,
  status: String,
  ports: List(String),
  created: Int,
)

Arguments

state: "running", "exited", "created", "paused", …
status: Docker’s human status, e.g. "Up 3 minutes".
ports: Published forwards, each HOST:GUEST/proto.
created: Unix epoch seconds.

DockerStatus

</>

The Docker engine VM: whether it is up, and how to reach it.

bsdkrun runs one docker:dind microVM and serves its API on a host unix socket, so the host’s own docker CLI drives the same engine.

pub type DockerStatus {
  DockerStatus(
    running: Bool,
    machine_id: option.Option(String),
    machine_running: Bool,
    socket: String,
    socket_ready: Bool,
    api_port: option.Option(Int),
    version: option.Option(String),
    containers: option.Option(Int),
    images: option.Option(Int),
    mounts: List(String),
    disk: option.Option(String),
    disk_size: option.Option(Int),
  )
}

Constructors

DockerStatus(
  running: Bool,
  machine_id: option.Option(String),
  machine_running: Bool,
  socket: String,
  socket_ready: Bool,
  api_port: option.Option(Int),
  version: option.Option(String),
  containers: option.Option(Int),
  images: option.Option(Int),
  mounts: List(String),
  disk: option.Option(String),
  disk_size: option.Option(Int),
)

Arguments

socket: The unix socket the docker CLI talks to.
mounts: Host directories shared into the VM, each HOST:GUEST.
disk: The dedicated image-store disk, when the VM has one.
disk_size: Its size in bytes — sparse, so the cap rather than the usage.

ExecResult

</>

The captured result of client.exec — a one-shot command run through openShell + shellOutput + closeShell (see bsdkrun/client).

Unlike the local CommandResult, output is a single interleaved BitArray rather than separate stdout/stderr: the daemon’s shell protocol is a pty, which does not keep the streams apart.

pub type ExecResult {
  ExecResult(exit_code: Int, output: BitArray)
}

Constructors

ExecResult(exit_code: Int, output: BitArray)

ImageInfo

</>

An image, as reported by bsdkrun images --json.

pub type ImageInfo {
  ImageInfo(
    id: String,
    reference: String,
    digest: String,
    size: Int,
    rootfs: String,
    created_at: Int,
  )
}

Constructors

ImageInfo(
  id: String,
  reference: String,
  digest: String,
  size: Int,
  rootfs: String,
  created_at: Int,
)

NetworkInfo

</>

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

pub type NetworkInfo {
  NetworkInfo(
    name: String,
    subnet: String,
    gateway: String,
    members: Int,
    running: Int,
    up: Bool,
    created_at: option.Option(Int),
  )
}

Constructors

NetworkInfo(
  name: String,
  subnet: String,
  gateway: String,
  members: Int,
  running: Int,
  up: Bool,
  created_at: option.Option(Int),
)

PortForward

</>

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

pub type PortForward {
  PortForward(bind: String, host: Int, guest: Int)
}

Constructors

PortForward(bind: String, host: Int, guest: Int)

RestoreResult

</>

What a bsdkrun cache restore --json did. A miss is not an error — check restored.

pub type RestoreResult {
  RestoreResult(
    restored: Bool,
    requested_key: String,
    key: option.Option(String),
    path: option.Option(String),
    size: option.Option(Int),
    compression: option.Option(String),
    created: option.Option(Int),
  )
}

Constructors

RestoreResult(
  restored: Bool,
  requested_key: String,
  key: option.Option(String),
  path: option.Option(String),
  size: option.Option(Int),
  compression: option.Option(String),
  created: option.Option(Int),
)

SandboxInfo

</>

A machine, as reported by bsdkrun ps --json.

pub type SandboxInfo {
  SandboxInfo(
    id: String,
    name: option.Option(String),
    image: String,
    kind: String,
    command: String,
    running: Bool,
    exit_code: option.Option(Int),
    pid: option.Option(Int),
    detached: Bool,
    cpus: Int,
    mem: Int,
    volume: option.Option(String),
    state_dir: String,
    network: option.Option(String),
    net_ip: option.Option(String),
    created_at: Int,
    finished_at: option.Option(Int),
    ports: List(PortForward),
    origin: option.Option(String),
  )
}

Constructors

SandboxInfo(
  id: String,
  name: option.Option(String),
  image: String,
  kind: String,
  command: String,
  running: Bool,
  exit_code: option.Option(Int),
  pid: option.Option(Int),
  detached: Bool,
  cpus: Int,
  mem: Int,
  volume: option.Option(String),
  state_dir: String,
  network: option.Option(String),
  net_ip: option.Option(String),
  created_at: Int,
  finished_at: option.Option(Int),
  ports: List(PortForward),
  origin: option.Option(String),
)

Arguments

origin: The snapshot this machine was branched from, if any.

ShellEvent

</>

One event from a live shellOutput or machineLogs subscription, as delivered to a bsdkrun/subject.Subject by bsdkrun/client.

pub type ShellEvent {
  ShellData(BitArray)
  ShellExit(Int)
  ShellError(String)
  ShellClosed
}

Constructors

```
ShellData(BitArray)
```
A chunk of output, already base64-decoded.
```
ShellExit(Int)
```
The session’s command exited. Terminal — no further events follow.
```
ShellError(String)
```
The subscription itself failed (a GraphQL error message, or the socket closing). Terminal.
```
ShellClosed
```
The subscription ended with no more data (a GraphQL complete, or the caller unsubscribed). Terminal.

ShellSessionInfo

</>

A shell session, as reported by the daemon’s openShell mutation / shellSessions query.

pub type ShellSessionInfo {
  ShellSessionInfo(
    id: String,
    machine_id: String,
    finished: Bool,
    truncated: Bool,
  )
}

Constructors

ShellSessionInfo(
  id: String,
  machine_id: String,
  finished: Bool,
  truncated: Bool,
)

SnapshotInfo

</>

A machine snapshot: one machine’s disk state, captured under a name.

A copy-on-write clone rather than a memory image — the files the guest wrote, not what it was executing. client.branch boots a new machine from one; client.restore puts one back over the machine it came from.

pub type SnapshotInfo {
  SnapshotInfo(
    id: String,
    name: String,
    machine_id: String,
    machine_name: String,
    kind: String,
    image: String,
    path: String,
    parent: option.Option(String),
    description: String,
    cpus: Int,
    mem: Int,
    ports: List(PortForward),
    size: option.Option(String),
    created_at: Int,
  )
}

Constructors

SnapshotInfo(
  id: String,
  name: String,
  machine_id: String,
  machine_name: String,
  kind: String,
  image: String,
  path: String,
  parent: option.Option(String),
  description: String,
  cpus: Int,
  mem: Int,
  ports: List(PortForward),
  size: option.Option(String),
  created_at: Int,
)

Arguments

machine_name: The machine’s name when it was taken; empty if it had none.
kind: "linux", "freebsd", "netbsd" or "unikraft".
parent: The snapshot the source machine was itself branched from, if any.
size: Human-readable, when measured — a CoW clone costs nothing to take.

SubscriptionEvent

</>

One event from client.subscribe, the generic subscription escape hatch.

pub type SubscriptionEvent {
  SubNext(dynamic.Dynamic)
  SubError(String)
  SubComplete
}

Constructors

```
SubNext(dynamic.Dynamic)
```
One next payload’s data, exactly as the operation’s document shapes it — decode it the same way you would decode client.request’s result.
```
SubError(String)
```
A GraphQL error message (or the socket closing). Terminal.
```
SubComplete
```
A GraphQL complete. Terminal.

VolumeInfo

</>

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

pub type VolumeInfo {
  VolumeInfo(
    name: String,
    guest: option.Option(String),
    base: option.Option(String),
    path: String,
    size: String,
    created_at: option.Option(Int),
    tracked: Bool,
  )
}

Constructors

VolumeInfo(
  name: String,
  guest: option.Option(String),
  base: option.Option(String),
  path: String,
  size: String,
  created_at: option.Option(Int),
  tracked: Bool,
)

Values

ai_agent_from_graphql

</>

pub fn ai_agent_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(AiAgent, error.Error)

Decode a GraphQL AiAgent object.

ai_session_from_graphql

</>

pub fn ai_session_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(AiSession, error.Error)

Decode a GraphQL AiSession object.

cache_entry_decoder

</>

pub fn cache_entry_decoder() -> decode.Decoder(CacheEntry)

Decoder for one cache ls --json row, and for cache save --json.

command_result_from_graphql

</>

pub fn command_result_from_graphql(
  dyn: dynamic.Dynamic,
  label: String,
) -> Result(CommandResult, error.Error)

Decode a GraphQL CommandResult object ({ exitCode stdout stderr }, what every lifecycle mutation returns) into the local CommandResult type. GraphQL’s CommandResult has no command field — the mutation name is supplied by the caller (bsdkrun/client) so error messages still name the operation that failed, exactly as the local CLI path does.

container_running

</>

pub fn container_running(c: DockerContainer) -> Bool

Whether a container is up.

decode_base64_chunk

</>

pub fn decode_base64_chunk(data_base64: String) -> BitArray

Base64-decode one shellOutput/machineLogs chunk’s dataBase64 field. Invalid base64 (should not happen — the daemon only ever sends what it itself encoded) decodes as empty, so a display glitch never becomes a crash.

decode_one

</>

pub fn decode_one(
  raw: String,
  label: String,
  row: decode.Decoder(a),
) -> Result(a, error.Error)

Decode a --json list payload. Blank output — which the CLI emits when there is nothing to list — decodes as the empty list. Decode a single JSON object, as decode_rows does for a list.

decode_rows

</>

pub fn decode_rows(
  raw: String,
  label: String,
  row: decode.Decoder(a),
) -> Result(List(a), error.Error)

docker_container_from_graphql

</>

pub fn docker_container_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(DockerContainer, error.Error)

Decode a GraphQL DockerContainer object.

docker_status_from_graphql

</>

pub fn docker_status_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(DockerStatus, error.Error)

Decode a GraphQL DockerStatus object.

image_info_decoder

</>

pub fn image_info_decoder() -> decode.Decoder(ImageInfo)

Decoder for one images --json row.

int_field

</>

pub fn int_field(
  dyn: dynamic.Dynamic,
  name: String,
  default: Int,
) -> Int

Decode a Dynamic’s Int field by name, defaulting to default when the field is absent, null, or the wrong shape.

is_ok

</>

pub fn is_ok(res: CommandResult) -> Bool

Whether the command succeeded (exit 0).

lines

</>

pub fn lines(res: CommandResult) -> List(String)

Non-empty stdout lines.

network_info_decoder

</>

pub fn network_info_decoder() -> decode.Decoder(NetworkInfo)

Decoder for one network ls --json row.

optional_string_field

</>

pub fn optional_string_field(
  dyn: dynamic.Dynamic,
  name: String,
) -> option.Option(String)

Decode a decode.optional_field(name, option.None, decode.optional(inner), next) shaped field returning a String. A convenience for the few call sites outside this module (bsdkrun/client) that need one field decoded out of a Dynamic without building a full record decoder.

port_forward_decoder

</>

pub fn port_forward_decoder() -> decode.Decoder(PortForward)

Decoder for one ports entry of a ps --json row.

restore_result_decoder

</>

pub fn restore_result_decoder() -> decode.Decoder(RestoreResult)

Decoder for cache restore --json.

sandbox_info_decoder

</>

pub fn sandbox_info_decoder() -> decode.Decoder(SandboxInfo)

Decoder for one ps --json row.

sandbox_info_from_graphql

</>

pub fn sandbox_info_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(SandboxInfo, error.Error)

Decode a GraphQL Machine object (the machine/machines query result, or data.machine from a raw client.request call) into a SandboxInfo.

shell_session_info_from_graphql

</>

pub fn shell_session_info_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(ShellSessionInfo, error.Error)

Decode a GraphQL ShellSessionInfo object (openShell’s result, or a row of shellSessions).

snapshot_info_from_graphql

</>

pub fn snapshot_info_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(SnapshotInfo, error.Error)

Decode a GraphQL Snapshot object into a SnapshotInfo.

status

</>

pub fn status(info: SandboxInfo) -> String

"running" or "exited" — the status column bsdkrun ps prints.

string_field

</>

pub fn string_field(
  dyn: dynamic.Dynamic,
  name: String,
  default: String,
) -> String

Decode a Dynamic’s String field by name, defaulting to default when the field is absent, null, or the wrong shape.

text

</>

pub fn text(res: CommandResult) -> String

stdout with trailing newlines trimmed — the common case.

volume_info_decoder

</>

pub fn volume_info_decoder() -> decode.Decoder(VolumeInfo)

Decoder for one volume ls --json row.