pub struct BoxConfig {Show 37 fields
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,
}Expand description
Box configuration
Fields§
§isolation: ExecutionIsolationExecution isolation. MicroVM is the backwards-compatible default.
image: StringOCI image reference (e.g., “nginx:alpine”, “ghcr.io/org/app:latest”)
workspace: PathBufWorkspace directory (mounted to /workspace inside the VM)
resources: ResourceConfigResource limits
log_level: LogLevelLog level
debug_grpc: boolEnable gRPC debug logging
tee: TeeConfigTEE (Trusted Execution Environment) configuration
cmd: Vec<String>Command override (replaces OCI CMD when set)
stdin_open: boolKeep 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: CacheConfigCache configuration for cold start optimization
pool: PoolConfigWarm pool configuration for pre-booted VMs
deferred_main: boolBoot 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: boolMark 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: NetworkModeNetwork 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: ResourceLimitsResource 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: boolRun in privileged mode (disables all security restrictions)
read_only: boolMount 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: boolPreserve 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.