Struct SandboxSpec 

pub struct SandboxSpec {

    pub name: Option<String>,
    pub image: String,
    pub instance_type: InstanceType,
    pub storage: Option<String>,
    pub cpus: Option<String>,
    pub cpuset: Option<String>,
    pub memory: Option<String>,
    pub privileged: Option<bool>,
    pub idmap: Option<IdmapSpec>,
    pub profiles: Option<Vec<String>>,
    pub labels: BTreeMap<String, String>,
    pub env: Environment,
    pub volumes: Vec<VolumeSpec>,
    pub ports: Vec<PortSpec>,
    pub ready: Option<Vec<ReadyCheck>>,
    pub ready_timeout: Option<String>,
    pub user: Option<String>,
    pub working_dir: Option<String>,
    pub exec: ExecSpec,
    pub command: Option<Vec<String>>,
    pub entrypoint: Option<Vec<String>>,
    pub restart: Option<RestartMode>,
    pub healthcheck: Option<Healthcheck>,
    pub depends_on: BTreeMap<String, Dependency>,
    pub deploy: Option<Deploy>,
    pub domains: Vec<DomainSpec>,
    pub secrets: Vec<SecretRef>,
    pub egress: Option<EgressSpec>,
    pub raw_config: BTreeMap<String, String>,
    pub raw_devices: BTreeMap<String, BTreeMap<String, String>>,
    pub workspace_nesting: bool,
    pub stack_udp: bool,
}

Everything about one sandbox: a compose service.

Fields

name: Option<String>

incus instance name: at most 63 characters of [a-z0-9-] (case-insensitive), starting with a letter. In a compose file it defaults to <project>-<service>.

image: String

Image: a local alias or fingerprint (dev-base), or remote:alias for a well-known remote (images:debian/12, ubuntu:24.04). A local alias that does not exist is an error before anything is created.

instance_type: InstanceType

container (default) or virtual-machine (vm). Fixed at creation.

A VM is a stronger boundary (its own kernel) at the cost of boot time and memory. Container-only settings are refused for a VM: privileged, and any explicit idmap (idmap: auto is a no-op there). Host paths are shared into a VM over virtiofs, where inotify from host edits is not delivered, so file watchers inside the VM need polling. Proxies into a VM must be host-bound, and incus runs them in NAT mode (nat: true, set automatically); bind: guest is not available for VMs.

storage: Option<String>

Storage pool for the root disk. auto (default): incus-zfs if it exists, else default, else the first pool. Fixed at creation.

cpus: Option<String>

Number of CPUs (limits.cpu), a whole number like 8.

cpuset: Option<String>

CPUs to pin to (limits.cpu), e.g. 0-3 or 0,2. Excludes cpus.

memory: Option<String>

Memory limit (limits.memory): docker units (512m, 8g, bytes) or incus ones (8GiB, 50%).

privileged: Option<bool>

Run privileged (security.privileged). Omit to leave the incus default (unprivileged); false pins it explicitly.

idmap: Option<IdmapSpec>

uid/gid mapping so a host user can write bind mounts. See IdmapSpec.

profiles: Option<Vec<String>>

incus profiles to apply, in order. Default: [default]. Fixed at creation.

labels: BTreeMap<String, String>

Labels, stored as user.<key> config keys: a map, or a list of KEY=VALUE. Used by isb ls --label and isb prune. isb never removes a label it was not told about.

env: Environment

Instance environment (environment.<KEY>), seen by every exec: a map, or a list of KEY=VALUE. A plain value is instance config, readable by anyone who can read the instance. KEY: {secret: NAME} delivers the top-level secret NAME as the variable (docs/guides/secrets.md).

volumes: Vec<VolumeSpec>

Mounts: SOURCE:TARGET[:OPTIONS] or the long form. A source starting with /, . or ~ is a host path; anything else is a named volume.

ports: Vec<PortSpec>

Published ports ([HOST_IP:]PUBLISHED:TARGET[/PROTOCOL] or the long form), and incus proxies in either direction (listen/connect).

ready: Option<Vec<ReadyCheck>>

Readiness checks, run in order after every start/ensure. Default: [running] for a container, [running, agent] for a VM.

ready_timeout: Option<String>

Deadline for all readiness checks together, e.g. 90s. Default: 60s for a container, 300s for a VM.

user: Option<String>

Guest user for command, isb exec and path_writable: a name (dev), uid, uid:gid or name:group. Default root.

working_dir: Option<String>

Working directory for command and isb exec. Default: the user’s home.

exec: ExecSpec

More exec defaults: an exec-only environment and the login shell.

command: Option<Vec<String>>

The sandbox’s main command, run by a foreground isb up once the sandbox is ready, as user in working_dir. Its output is streamed, and up stops the sandbox when every command has exited. A list is argv; a string is split like a shell would split it, without running one. Never part of the instance, so changing it is not drift.

entrypoint: Option<Vec<String>>

OCI images only: the entrypoint, run with command as its arguments. On an OCI image command alone replaces the whole command line, including the image’s own entrypoint.

restart: Option<RestartMode>

no (default), always, on-failure or unless-stopped. Anything but no makes the service long-running: the instance starts with the host (boot.autostart), and command is supervised inside the guest (a systemd unit, or the instance itself for an OCI image) instead of being held open by isb up, so it survives isb exiting.

healthcheck: Option<Healthcheck>

A recurring health test, as in docker compose. isb stack deploy routes traffic only to healthy replicas and replaces unhealthy ones; depends_on can wait for it.

depends_on: BTreeMap<String, Dependency>

Services to bring up first: a list, or a map to {condition: service_started | service_healthy}.

deploy: Option<Deploy>

Replicas, rolling updates and restart policy for isb stack deploy.

domains: Vec<DomainSpec>

Public hostnames isb serve’s ingress routes to this service’s replicas (docs/guides/domains.md). Only stacks use them; isb up ignores them.

secrets: Vec<SecretRef>

Secrets (top-level secrets:) to write under /run/secrets in the guest: names, or {source, target, uid, gid, mode}.

egress: Option<EgressSpec>

Which hostnames the sandbox may reach, and secrets that never enter it (docs/guides/egress.md). none denies all network; a list of host[:port] (port 443 by default; *.example.com for subdomains) denies everything else, public and private; {allow, secrets} adds secrets the guest sees only as placeholders, put on the wire towards their approved hosts. Omitted: open egress, as before. Needs isb serve running for its proxy.

raw_config: BTreeMap<String, String>

Extra instance config keys, set verbatim (escape hatch).

raw_devices: BTreeMap<String, BTreeMap<String, String>>

Extra devices, set verbatim (escape hatch). Keys are device names.

workspace_nesting: bool

Nesting keys allowed: only the daemon sets it, for a workspace (crate::org::nesting).

stack_udp: bool

UDP proxy devices allowed: only the stack controller sets it, for a replica’s published UDP ports (crate::org::check_proxies).

Implementations

impl SandboxSpec

pub fn new(name: impl Into<String>, image: impl Into<String>) -> Self

pub fn cpus(self, cpus: impl ToString) -> Self

pub fn cpuset(self, set: impl Into<String>) -> Self

pub fn memory(self, m: impl Into<String>) -> Self

pub fn storage(self, pool: impl Into<String>) -> Self

pub fn idmap(self, idmap: IdmapSpec) -> Self

pub fn privileged(self, p: bool) -> Self

pub fn label(self, k: impl Into<String>, v: impl Into<String>) -> Self

pub fn env(self, k: impl Into<String>, v: impl Into<String>) -> Self

pub fn egress(self, e: EgressSpec) -> Self

Restrict the sandbox’s network: see crate::egress::EgressSpec.

pub fn volume(self, guest_path: impl Into<String>, vol: VolumeSpec) -> Self

Mount vol at guest_path.

pub fn port(self, p: PortSpec) -> Self

pub fn ready(self, checks: Vec<ReadyCheck>) -> Self

pub fn ready_timeout(self, t: impl Into<String>) -> Self

pub fn user(self, u: impl Into<String>) -> Self

pub fn working_dir(self, c: impl Into<String>) -> Self

pub fn raw_config(self, k: impl Into<String>, v: impl Into<String>) -> Self

pub fn raw_device( self, name: impl Into<String>, props: BTreeMap<String, String>, ) -> Self

impl SandboxSpec

pub fn exec_defaults(&self) -> ExecDefaults

The exec defaults this spec implies: user, working_dir and exec.

impl SandboxSpec

pub fn secret_keys(&self) -> BTreeSet<&str>

Every top-level secret the service uses, as a file or a variable.

pub fn long_running(&self) -> bool

restart is set to something that keeps the service running.

pub fn replicas(&self) -> u32

deploy.replicas, default 1.

pub fn health_probe(&self) -> Result<Option<HealthProbe>, String>

The health probe, if any.

Trait Implementations

impl Clone for SandboxSpec

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SandboxSpec

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

Formats the value using the given formatter.

impl Default for SandboxSpec

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SandboxSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for SandboxSpec

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl PartialEq for SandboxSpec

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for SandboxSpec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SandboxSpec