Struct BoxConfig 

pub struct BoxConfig {

    pub isolation: ExecutionIsolation,
    pub image: String,
    pub workspace: PathBuf,
    pub resources: ResourceConfig,
    pub log_level: LogLevel,
    pub debug_grpc: bool,
    pub tee: TeeConfig,
    pub cmd: Vec<String>,
    pub stdin_open: bool,
    pub entrypoint_override: Option<Vec<String>>,
    pub user: Option<String>,
    pub workdir: Option<String>,
    pub hostname: Option<String>,
    pub volumes: Vec<String>,
    pub virtiofs_cache: Option<String>,
    pub extra_env: Vec<(String, String)>,
    pub cache: CacheConfig,
    pub pool: PoolConfig,
    pub deferred_main: bool,
    pub ksm: bool,
    pub snapshot_mem_file: Option<String>,
    pub snapshot_sock: Option<String>,
    pub restore_from: Option<String>,
    pub port_map: Vec<String>,
    pub dns: Vec<String>,
    pub add_hosts: Vec<String>,
    pub network: NetworkMode,
    pub tmpfs: Vec<String>,
    pub resource_limits: ResourceLimits,
    pub cap_add: Vec<String>,
    pub cap_drop: Vec<String>,
    pub security_opt: Vec<String>,
    pub sysctls: Vec<(String, String)>,
    pub privileged: bool,
    pub read_only: bool,
    pub sidecar: Option<SidecarConfig>,
    pub persistent: bool,
}

Box configuration

Fields

isolation: ExecutionIsolation

Execution isolation. MicroVM is the backwards-compatible default.

image: String

OCI image reference (e.g., “nginx:alpine”, “ghcr.io/org/app:latest”)

workspace: PathBuf

Workspace directory (mounted to /workspace inside the VM)

resources: ResourceConfig

Resource limits

log_level: LogLevel

Log level

debug_grpc: bool

Enable gRPC debug logging

tee: TeeConfig

TEE (Trusted Execution Environment) configuration

cmd: Vec<String>

Command override (replaces OCI CMD when set)

stdin_open: bool

Keep stdin open for the initial container process.

Defaults to false so non-interactive runs do not block forever on prompts.

entrypoint_override: Option<Vec<String>>

Entrypoint override (replaces OCI ENTRYPOINT when set)

user: Option<String>

User override for the initial container process.

Supported runtime format is a numeric uid or uid:gid.

workdir: Option<String>

Working directory override for the initial container process.

hostname: Option<String>

Hostname to apply inside the box.

volumes: Vec<String>

Extra volume mounts (host_path:guest_path or host_path:guest_path:ro)

virtiofs_cache: Option<String>

virtio-fs cache mode for host directory volumes (none, auto, always, or default). None uses the host environment/default.

extra_env: Vec<(String, String)>

Extra environment variables for the entrypoint

cache: CacheConfig

Cache configuration for cold start optimization

pool: PoolConfig

Warm pool configuration for pre-booted VMs

deferred_main: bool

Boot the VM IDLE — do not spawn the container main at boot; instead the main is started later by a spawn-main control frame. Used by the pool so a pre-warmed sandbox runs a per-request command as its real main, with full box semantics (exit code + json-file console logs) and no cold boot.

ksm: bool

Mark guest memory KSM-mergeable so the host kernel dedups identical pages across same-image VMs (Linux 6.4+; needs /sys/kernel/mm/ksm/run=1 on the host). Most valuable for pools of same-image sandboxes.

snapshot_mem_file: Option<String>

Snapshot-fork (per-VM): file-backed guest RAM path for a snapshot TEMPLATE (paired with snapshot_sock), or the RAM file to MAP_PRIVATE CoW-restore from (paired with restore_from).

snapshot_sock: Option<String>

Snapshot-fork (per-VM): unix socket on which libkrun serves snapshot requests for a template VM.

restore_from: Option<String>

Snapshot-fork (per-VM): state file to RESTORE from — this VM resumes the snapshotted template (CoW of snapshot_mem_file) instead of cold-booting. The per-VM seam that lets one process (pool / fork daemon) fork many VMs.

port_map: Vec<String>

Port mappings: “host_port:guest_port” (e.g., “8080:80”) Maps host ports to guest ports via TSI (Transparent Socket Impersonation).

dns: Vec<String>

Custom DNS servers (e.g., “1.1.1.1”). If empty, reads from host /etc/resolv.conf, falling back to 8.8.8.8.

add_hosts: Vec<String>

Static host-to-IP mappings for /etc/hosts (HOST:IP).

network: NetworkMode

Network mode: TSI (default), bridge (passt-based), or none.

tmpfs: Vec<String>

tmpfs mounts (ephemeral in-guest filesystems). Format: “/path” or “/path:size=100m”

resource_limits: ResourceLimits

Resource limits (PID limits, CPU pinning, ulimits, cgroup controls).

cap_add: Vec<String>

Linux capabilities to add (e.g., “NET_ADMIN”, “SYS_PTRACE”)

cap_drop: Vec<String>

Linux capabilities to drop (e.g., “ALL”, “NET_RAW”)

security_opt: Vec<String>

Security options (e.g., “seccomp=unconfined”, “no-new-privileges”)

sysctls: Vec<(String, String)>

Kernel sysctls (name → value) applied in the guest at boot.

Pod-level sysctls from the CRI PodSandboxConfig; the guest writes each to /proc/sys/<name with '.' as '/'> once the VM is up.

privileged: bool

Run in privileged mode (disables all security restrictions)

read_only: bool

Mount the container rootfs as read-only.

Volume mounts (-v host:guest) remain writable by default. Requires guest init to be present in the rootfs image.

sidecar: Option<SidecarConfig>

Optional sidecar process to run alongside the main container inside the VM.

The sidecar is launched before the main container entrypoint and runs as a co-process inside the same MicroVM. Intended for security proxies such as SafeClaw that intercept and classify agent traffic.

persistent: bool

Preserve the box filesystem across stop/start cycles.

When true, the overlay upper layer (or copy rootfs) is kept on disk after the box stops and reused on the next start. Changes made inside the box persist between restarts, similar to a traditional VM.

When false (default), the writable layer is wiped on every stop, giving a clean slate on each start.

Trait Implementations

impl Clone for BoxConfig

fn clone(&self) -> BoxConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BoxConfig

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

Formats the value using the given formatter.

impl Default for BoxConfig

fn default() -> BoxConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BoxConfig

fn deserialize<__D>( __deserializer: __D, ) -> Result<BoxConfig, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for BoxConfig

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

where __S: Serializer,

Serialize this value into the given Serde serializer.