Crate isb 

isb: declarative incus sandboxes

A library, a CLI and a compose-style YAML format for incus containers (and VMs) used as sandboxes. isb talks to incusd over its unix socket, never through the incus binary, so every request has a deadline and every stall is reported as the step that stalled.

use isb::{Client, Sandbox, SandboxSpec, Volume, PortBinding, ReadyCheck};

let client = Client::new();
let spec = SandboxSpec::new("dev-web", "dev-base")
    .cpus(8)
    .memory("8GiB")
    .label("app", "web")
    .volume("/home/dev/src", Volume::bind("./src").device("src"))
    .volume("/home/dev/.cache", Volume::named("dev-cache").owner("dev"))
    .port(PortBinding::host("tcp:127.0.0.1:5173", "tcp:127.0.0.1:5173"))
    .ready(vec![ReadyCheck::Running, ReadyCheck::DefaultRoute]);
// Creates it if missing; otherwise changes only what differs.
let sb = Sandbox::connect_or_create(&client, &spec)?;
let out = sb.exec(["uname", "-a"])?;
println!("{}", out.stdout_text());

The spec model (spec) is shared by the library, the CLI flags and the YAML, and plan turns a spec plus the instance’s actual state into the minimal set of changes. A device that is already correct is never touched.

Modules

app

Applications: the Dokploy-style object over stacks.

audit

The audit log: who did what, where, through which door, and how it went.

auth

Identity for isb serve: users, org memberships and roles, browser sessions, invitations, API tokens and password resets, in SQLite at <state>/isb.db.

backup

Database backups to S3-compatible storage, and restores from them.

balance

An L4 (TCP) load balancer for published ports.

build

Builds: turn a source tree into an OCI image in the org’s registry.

client

A small, synchronous incusd REST client over the local unix socket.

compose

Loading compose files: -f a.yaml -f b.yaml, interpolation, defaults.

cron

Cron schedules: the five-field form (minute hour day-of-month month day-of-week) and the @hourly-style aliases, evaluated in UTC or a fixed offset from it.

daemon

isb serve: the stack controller behind an MCP server.

discovery

Service discovery: stable DNS names for a stack’s services inside an org.

egress

Per-sandbox egress policy: an allowlist of host[:port] a sandbox may reach, and secrets that never enter the guest.

egress_proxy

isb’s per-sandbox egress proxy: hostname allowlists, and secrets that never enter the guest.

error

exec

Running commands in a sandbox over the incus exec websocket API.

foreground

Foreground isb up: run each sandbox’s command, stream its output, and stop the sandboxes when it is over.

history

The history: everything that happened to what isb runs, kept so the current state can always be traced back.

idmap

Deciding whether a sandbox needs raw.idmap.

image_check

Does a remote image exist? Asked before an app or a stack service names one, so a typo is refused up front instead of deployed into a replica that fails to pull, and asked again at each deploy, where its answer is also the digest the image is pinned to.

ingress

Ingress: public hostnames for stack services (docs/guides/domains.md).

interp

Compose-style variable interpolation.

jobs

Scheduled jobs: a command run on a cron schedule against an app or a stack service of an org.

lock

Per-sandbox lock, so two concurrent up/ensure calls do not both create.

machine

isb machine: incus runs only on Linux, so on macOS isb manages a Lima VM that runs it, the way podman machine does.

metrics

Live numbers for dashboards: the host’s CPU, memory and storage, and every instance’s status, address, CPU, memory and disk, each with a short history for sparklines.

metrics_history

Metrics history: the sampler’s per-instance CPU, memory, network and disk numbers, kept for a month in downsampling tiers, per org, across daemon restarts.

monitor

Uptime monitors: what users see of an org’s apps, checked from outside the app every interval, with history, incidents and notifications.

net

Outbound connections held to an address policy (notifications, and whatever else dials an address an org member chose).

notify

Notifications: per-org channels (webhook, Slack, Discord, Telegram, email) told about events of chosen kinds (deploy.*, health.*, backup.*, job.*, cert.*, monitor.*; see crate::stack::controller::Event).

org

Orgs: the trust boundary. An org is an incus project; its people and agents fully administer what is in it, and nothing crosses orgs.

owner

A named volume’s mount point: its owner and mode, set from the host.

plan

Resolve a spec into desired incus state, and diff it against actual state.

registry

The local OCI registry: where builds push and incus pulls.

rpc

isb rpc: the protocol the language SDKs speak.

s3

A small S3 client for backups: AWS Signature Version 4 over ring and ureq, no SDK.

sandbox

The sandbox API and the apply engine.

secrets

Secrets: named values per org, behind pluggable drivers.

self_update

isb update: replace the running isb with a release from GitHub.

server

isb serve: the MCP server layer, with the tools supplied by the embedder.

servers

Remote servers (P5.1, P5.2): a control plane places orgs on other hosts, each running incus and isb serve --agent, and forwards their calls over mutual TLS. Federation, not incus clustering: every server is a whole isb (controller, ingress, registry, builds, secrets) for the orgs on it. See docs/guides/servers.md.

sftp

Just enough SFTP (version 3) to stat, chown and chmod a path inside an instance through incus’ /1.0/instances/NAME/sftp.

shorthand

Command-line shorthands for mounts, ports, labels and readiness checks.

spec

The one spec model shared by the library API, the CLI and the compose YAML.

stack

Stacks: a compose file deployed to the isb serve daemon, which keeps it running the way docker swarm keeps a stack running, on one host.

supervise

Long-running services: the app is supervised inside the guest, never held open by an isb process, so it outlives isb up, a daemon restart or an isb upgrade.

template

Templates: one-click apps.

tui

isb tui: a terminal dashboard for stacks and sandboxes.

volume

Named custom storage volumes.

volume_backup

Snapshots, backups and staged restores of an org’s named volumes: an app’s <app>_<NAME>, a database’s data, a workspace’s home. Generic over “a custom volume in the org’s incus project”; crate::volume is the raw incus helper underneath.

web

The web UI, embedded at build time (see build.rs) and served by isb serve on its TCP listener.

workspace

Workspaces (docs/concepts/workspaces.md): an org’s long-lived machine, where its people and agents work, and the rules for the short-lived sandboxes beside it.

Structs

ApplyReport

What apply did.

Client

Connection to incusd.

ComposeFile

A compose file: named volumes plus any number of services, each one sandbox. Mirrors docker compose wherever incus allows.

DiffOptions

Options for diff.

EnsureOptions

Options for ensure / up.

ExecController

A cloneable handle for driving a running command (stdin, signals, window size) from other threads while one thread reads its output.

ExecDefaults

Defaults for exec into a sandbox. Per-call options override them.

ExecOptions

Per-call exec options. Unset fields fall back to the sandbox’s exec defaults.

ExecOutput

Captured result of crate::Sandbox::exec.

ExecStream

A running command. Iterate it for output; ExecStream::wait for the exit code.

IdmapMap

IdmapRaw

LabelFilter

key (present) or key=value (equal).

LoadOptions

How to load.

NamedVolumeSpec

A named custom storage volume.

PortBinding

Port binding builders.

PortSpec

An incus proxy device. Written as docker’s [HOST_IP:]PUBLISHED:TARGET[/PROTOCOL], its long form (PortMapping in the schema), or the incus form (ProxyPort).

Project

A loaded, interpolated, merged compose project.

Sandbox

A handle on one sandbox.

SandboxInfo

A summary of an instance, as listed.

SandboxPlan

The plan for one sandbox.

SandboxSpec

Everything about one sandbox: a compose service.

Timeouts

Deadlines used by the client. Every request has one; there is no unbounded wait anywhere except the output of exec, which by design has no default timeout.

Volume

Mount builders: Volume::bind(host), Volume::named(name).

VolumeSpec

A mount. Written as SOURCE:TARGET[:OPTIONS] or as the long form (VolumeMount in the schema); always serialized in the long form.

Enums

Action

One step of a plan.

Error

Everything isb can fail with.

ExecEvent

A chunk of output, in the order it was produced per stream.

IdmapMode

IdmapSpec

idmap handling.

InstanceType

Instance type.

PortBind

Which side listens.

ReadyCheck

A readiness check. “Running” alone is not ready: networking comes up a beat after the instance does.

Stdin

Where the command’s stdin comes from.

Functions

parse_duration

Parse 90, 90s, 5m, 1h, 90d, 1500ms into a duration.

Type Aliases

Result