Crate heyo_sdk 

Rust SDK for the Heyo cloud sandbox API.

Mirrors sdk-ts/ (@heyocomputer/sdk). The public surface is centered on three handles:

• Sandbox — VM lifecycle, with .commands() and .files() sub-clients and an interactive WebSocket ShellSession.
• Database — cloud sqlite databases with exec, connection tokens, and checkout/checkin for offline editing.
• HeyoClient — the underlying HTTP transport. Built from HeyoClientOptions (or constructed implicitly by the high-level create/connect helpers).

use heyo_sdk::{Sandbox, SandboxCreateOptions, HeyoClientOptions};

let sandbox = Sandbox::create(
    SandboxCreateOptions { image: Some("ubuntu:24.04".into()), ..Default::default() },
    HeyoClientOptions::default(),
).await?;
let out = sandbox.commands().run("echo hi", Default::default()).await?;
assert_eq!(out.stdout.trim(), "hi");
sandbox.kill().await?;

Structs

ArchiveDirOptions

ArchiveResult

BatchResult

BoundUrl

CheckinOptions

CheckinResult

CheckoutResult

CommandResult

CommandRunOptions

Commands

Command-execution surface, obtained via crate::Sandbox::commands.

ConnectionToken

ConnectionTokenInfo

ConnectionTokenOptions

DaemonInfo

A daemon the authenticated user has registered with the cloud.

Daemons

Static API for managing the caller’s registered daemons.

Database

DatabaseCreateOptions

DatabaseInfo

ExecOptions

ExecResult

FileOptions

Options for Files::read / Files::write.

Files

File-system surface, obtained via crate::Sandbox::files.

HeyoClient

HeyoClientOptions

Construction options for HeyoClient. Mirrors HeyoClientOptions in sdk-ts/src/client.ts.

Network

NetworkCreateOptions

NetworkInfo

NetworkMember

NetworkMemberRegistration

NetworkService

A private service route registered in a network — a name:port address other members can reach. When connection_url is set the service has a live iroh proxy route; otherwise it’s agent_proxy_pending until someone runs heyvm network expose-service.

NetworkUpdateOptions

P2pTunnel

A live P2P tunnel: a local TCP listener forwarding to a remote peer’s TCP service over iroh. The background forwarding task is aborted on Drop, which closes the local listener — hold this value for as long as the tunnel is needed.

PublicImage

RequestOptions

Optional per-request knobs.

Sandbox

SandboxCreateOptions

Options accepted by Sandbox::create. All fields except image/region may be left unset; the server applies defaults.

SandboxInfo

ServiceRoute

Result of dialing a service: a live route to it. connection_url is a heyo:// ticket consumable by P2pTunnel::connect.

ShellOptions

Options for crate::Sandbox::shell.

ShellReconnectOptions

Reconnect tuning.

ShellSession

A live shell session. Use output() for stdout chunks, events() for lifecycle events, and write() / resize() / close() to drive it.

SqlStatement

Enums

ConnectionScope

DaemonStatus

Status the cloud reports for a registered daemon. Derived from the cloud’s stale-host watcher: Online means a fresh heartbeat within ~3 minutes, Stale means missed heartbeats, Offline means the cloud has flipped the row away from available.

FileContent

Discriminated content for Files::write. String is encoded as UTF-8; Bytes is written verbatim.

HeyoError

Every fallible call in the SDK returns Result<T, HeyoError>. Variants mirror the TypeScript SDK’s error classes so the same recovery patterns translate across languages.

NetworkMemberKind

SandboxDriver

SandboxRegion

US or EU. The wire field is uppercase; we preserve that.

SandboxSize

SandboxStatus

Lifecycle states the cloud reports.

ShellEvent

Lifecycle events emitted on the session’s event stream.

SqlTransactionMode

SqlValue

SQL bind values. The cloud only accepts these scalars.

Constants

DEFAULT_LOCAL_BASE_URL

Default base URL for a local heyvm API (the heyvmd daemon’s --api-port). Used by HeyoClient::local so desktop apps can drive a same-machine sandbox without the cloud in the data path.

Functions

archive_dir

Tar+gzip local_path and upload it as a sandbox archive.