Struct Client 

pub struct Client { /* private fields */ }

A client for a remote bsdkrund’s GraphQL API.

Queries and mutations go over HTTP; subscriptions (used internally by Client::exec, Client::shell and Client::follow_logs) share one lazily opened graphql-transport-ws socket per client, torn down once the last subscription ends. Cloning is cheap and shares that socket.

Implementations

impl Client

pub fn new(url: impl Into<String>, token: impl Into<String>) -> Result<Client>

Build a client from a daemon URL and its bearer token.

A URL configured without a token is refused rather than silently making an unauthenticated request — the daemon has no anonymous tier.

pub fn from_env() -> Result<Client>

Build a client from BSDKRUN_URL / BSDKRUN_TOKEN.

Errors if BSDKRUN_URL is unset (nothing to connect to), or if it is set but BSDKRUN_TOKEN is not — a host configured without a token is a configuration error, never a silent fall-back to an unauthenticated request.

pub fn url(&self) -> &str

The normalized GraphQL endpoint URL.

pub fn request(&self, query: &str, variables: Value) -> Result<Value>

Run a raw query or mutation and return its data.

pub fn subscribe( &self, query: &str, variables: Value, on_next: impl FnMut(Value) + Send + 'static, ) -> Result<Subscription>

Start a raw subscription; each next payload’s data goes to on_next. Returns a Subscription handle to end it with.

pub fn subscribe_with( &self, query: &str, variables: Value, on_next: impl FnMut(Value) + Send + 'static, on_error: impl FnMut(Error) + Send + 'static, on_complete: impl FnMut() + Send + 'static, ) -> Result<Subscription>

Client::subscribe with error/completion callbacks.

pub fn list(&self, all: bool) -> Result<Vec<SandboxInfo>>

List machines. all includes exited ones.

pub fn get(&self, id: &str) -> Result<Option<SandboxInfo>>

Fetch one machine by id (a unique prefix) or name, or None.

pub fn stop(&self, id: &str) -> Result<CommandResult>

pub fn start(&self, id: &str) -> Result<CommandResult>

pub fn remove<S: AsRef<str>>( &self, ids: &[S], force: bool, ) -> Result<CommandResult>

pub fn update( &self, id: &str, cpus: Option<u32>, mem: Option<u32>, ) -> Result<CommandResult>

Change a machine’s recorded vCPU / memory; applies on its next start.

pub fn commit( &self, id: &str, name: &str, description: &str, ) -> Result<CommandResult>

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

pub fn ai_agents(&self) -> Result<Vec<AiAgent>>

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

pub fn ai_sessions(&self) -> Result<Vec<AiSession>>

Agent sandboxes, newest first.

pub fn ai_start(&self, agent: impl Into<String>) -> AiStartBuilder

Start (or reuse) a sandbox — see AiStartBuilder.

pub fn ai_shell_command( &self, agent: &str, machine_id: &str, ) -> Result<Vec<String>>

The argv that starts the agent’s TUI — pass it to Client::shell.

pub fn ai_stop(&self, agent: &str) -> Result<CommandResult>

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

pub fn ai_remove(&self, agent: &str, keep_home: bool) -> Result<CommandResult>

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

pub fn docker_status(&self) -> Result<DockerStatus>

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

pub fn docker_containers(&self, all: bool) -> Result<Vec<DockerContainer>>

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

pub fn docker_start(&self) -> DockerStartBuilder

Start (or resume) the engine — see DockerStartBuilder.

Idempotent: the VM has a fixed name, so this resumes the existing one rather than creating a second.

pub fn docker_stop(&self) -> Result<CommandResult>

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

pub fn docker_container<S: AsRef<str>>( &self, action: &str, ids: &[S], ) -> Result<CommandResult>

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

pub fn docker_logs(&self, id: &str, tail: u32) -> Result<String>

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

pub fn snapshots(&self, machine: Option<&str>) -> Result<Vec<SnapshotInfo>>

Snapshots, newest first. machine narrows to one machine’s.

pub fn snapshot( &self, id: &str, name: Option<&str>, description: &str, ) -> Result<SnapshotInfo>

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; Client::start brings it back.

pub fn remove_snapshots<S: AsRef<str>>( &self, names: &[S], ) -> Result<CommandResult>

Delete snapshots and their data. Machines branched from them stay.

pub fn restore( &self, id: &str, snapshot: &str, force: bool, backup: bool, ) -> Result<CommandResult>

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

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

pub fn rollback( &self, id: &str, force: bool, backup: bool, ) -> Result<CommandResult>

Restore a machine to its most recent snapshot.

pub fn branch(&self, snapshot: impl Into<String>) -> BranchBuilder

Boot a NEW machine from a snapshot — see BranchBuilder.

The snapshot is cloned, never booted in place, so the machine it came from is untouched and one snapshot can be branched any number of times.

pub fn logs(&self, id: &str, boot: bool) -> Result<String>

One-shot read of a machine’s console log (bsdkrun’s boot log with boot).

pub fn follow_logs(&self, id: &str) -> FollowLogsBuilder

Stream a machine’s console log live.

let sub = client
    .follow_logs("abc123")
    .on_data(|bytes| print!("{}", String::from_utf8_lossy(&bytes)))
    .start()?;

pub fn run_linux(&self) -> RunLinuxBuilder

Boot a Linux machine on the daemon — runLinux.

pub fn run_bsd(&self, os: BsdOs) -> RunBsdBuilder

Boot FreeBSD or NetBSD on the daemon — runBsd.

pub fn run_nanos(&self) -> RunNanosBuilder

Boot a Nanos unikernel on the daemon — runNanos.

pub fn run_unikraft(&self) -> RunUnikraftBuilder

Boot a Unikraft unikernel on the daemon — runUnikraft.

pub fn run_solo5(&self) -> RunSolo5Builder

Boot a Solo5 (MirageOS) unikernel on the daemon — runSolo5. Runs under the solo5-hvt tender rather than libkrun; the unikernel declares its own devices in its MFT1 manifest, so only block backings and its own args are passed.

pub fn run_osv(&self) -> RunOsvBuilder

Boot an OSv unikernel on the daemon — runOsv.

pub fn run_flavor(&self, name: impl Into<String>) -> RunFlavorBuilder

Boot a named flavor on the daemon — runFlavor.

pub fn exec<I, S>(&self, id: &str, command: I) -> Result<RemoteExecResult>

where I: IntoIterator<Item = S>, S: Into<String>,

Run a command to completion via the machine’s shell agent.

pub fn exec_with_env<I, S, E, T>( &self, id: &str, command: I, env: E, ) -> Result<RemoteExecResult>

where I: IntoIterator<Item = S>, S: Into<String>, E: IntoIterator<Item = T>, T: Into<String>,

Client::exec with per-command "K=V" environment entries.

Sequenced exactly as daemon/README.md describes: openShell (with command set, so the session runs it instead of a login shell), THEN subscribe to shellOutput (output is buffered from the moment the session opened, so nothing is lost even though the subscribe necessarily happens after the mutation), collecting bytes until an event carries a non-null exit code, THEN closeShell — called unconditionally, including on error, since it is idempotent and a session must never be left dangling.

pub fn shell(&self, id: &str) -> ShellBuilder

Open a live interactive session — output/exit arrive via callbacks.

let session = client.shell("abc123").rows(50).cols(120).open()?;
session.on_output(|bytes| print!("{}", String::from_utf8_lossy(bytes)));
session.on_exit(|code| println!("exited {code}"));
session.write("ls -la\n")?;

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.