> ## Documentation Index > Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt > Use this file to discover all available pages before exploring further. # Box Configuration > Rust SDK box configuration and options ## BoxOptions Options for constructing a box. ```rust theme={null} pub struct BoxOptions { /// Number of CPUs (default: 1) pub cpus: Option, /// Memory in MiB (default: 512) pub memory_mib: Option, /// Disk size in GB for rootfs (sparse, grows as needed) pub disk_size_gb: Option, /// Working directory inside box pub working_dir: Option, /// Environment variables pub env: Vec<(String, String)>, /// Root filesystem source pub rootfs: RootfsSpec, /// Volume mounts pub volumes: Vec, /// Network isolation mode pub network: NetworkSpec, /// Port mappings pub ports: Vec, /// Enable bind mount isolation (Linux only) pub isolate_mounts: bool, /// Auto-remove box when stopped (default: true) pub auto_remove: bool, /// Run independently of parent process (default: false) pub detach: bool, /// Security isolation options pub security: SecurityOptions, } ``` ### Example ```rust theme={null} use boxlite::runtime::options::{BoxOptions, RootfsSpec, VolumeSpec, PortSpec}; let options = BoxOptions { cpus: Some(4), memory_mib: Some(2048), rootfs: RootfsSpec::Image("python:3.11".to_string()), env: vec![ ("PYTHONPATH".to_string(), "/app".to_string()), ], volumes: vec![ VolumeSpec { host_path: "/home/user/project".to_string(), guest_path: "/app".to_string(), read_only: false, }, ], ports: vec![ PortSpec { host_port: Some(8080), guest_port: 80, ..Default::default() }, ], auto_remove: false, // Keep box after stop detach: true, // Run independently ..Default::default() }; ``` *** ## RootfsSpec How to populate the box root filesystem. ```rust theme={null} pub enum RootfsSpec { /// Pull/resolve this registry image reference Image(String), /// Use already prepared rootfs at host path RootfsPath(String), } impl Default for RootfsSpec { fn default() -> Self { Self::Image("alpine:latest".into()) } } ``` *** ## VolumeSpec Filesystem mount specification. ```rust theme={null} pub struct VolumeSpec { /// Path on host pub host_path: String, /// Path inside guest pub guest_path: String, /// Mount as read-only pub read_only: bool, } ``` *** ## NetworkSpec Network isolation options. ```rust theme={null} pub enum NetworkSpec { /// Isolated network with gvproxy (default) Isolated, // Host, // Future: share host network // Custom, // Future: custom network config } ``` *** ## PortSpec Port mapping specification (host to guest). ```rust theme={null} pub struct PortSpec { /// Host port (None/0 = dynamically assigned) pub host_port: Option, /// Guest port to expose pub guest_port: u16, /// Protocol (TCP/UDP) pub protocol: PortProtocol, /// Bind IP (None = 0.0.0.0) pub host_ip: Option, } pub enum PortProtocol { Tcp, // default Udp, } ``` *** ## SecurityOptions Security isolation options for a box. ```rust theme={null} pub struct SecurityOptions { /// Enable jailer isolation (Linux: seccomp/namespaces, macOS: sandbox-exec) pub jailer_enabled: bool, /// Enable seccomp syscall filtering (Linux only) pub seccomp_enabled: bool, /// UID to drop to (Linux only). None = auto-allocate pub uid: Option, /// GID to drop to (Linux only). None = auto-allocate pub gid: Option, /// Create new PID namespace (Linux only) pub new_pid_ns: bool, /// Create new network namespace (Linux only) pub new_net_ns: bool, /// Base directory for chroot jails (Linux) pub chroot_base: PathBuf, /// Enable chroot isolation (Linux only) pub chroot_enabled: bool, /// Close inherited file descriptors pub close_fds: bool, /// Sanitize environment variables pub sanitize_env: bool, /// Environment variables to preserve pub env_allowlist: Vec, /// Resource limits pub resource_limits: ResourceLimits, /// Custom sandbox profile (macOS only) pub sandbox_profile: Option, /// Enable network in sandbox (macOS only) pub network_enabled: bool, } ``` ### Presets ```rust theme={null} // Development: minimal isolation for debugging let dev = SecurityOptions::development(); // - jailer_enabled: false // - seccomp_enabled: false // - close_fds: false // Standard: recommended for most use cases let std = SecurityOptions::standard(); // - jailer_enabled: true (Linux/macOS) // - seccomp_enabled: true (Linux) // Maximum: all isolation features let max = SecurityOptions::maximum(); // - All isolation enabled // - uid/gid: 65534 (nobody) // - Resource limits applied ``` *** ## SecurityOptionsBuilder Fluent builder for security options. ```rust theme={null} use boxlite::runtime::options::{SecurityOptions, SecurityOptionsBuilder}; let security = SecurityOptionsBuilder::standard() .jailer_enabled(true) .max_open_files(2048) .max_file_size_bytes(1024 * 1024 * 512) // 512 MiB .max_processes(100) .allow_env("MY_VAR") .build(); // Or via SecurityOptions::builder() let security = SecurityOptions::builder() .jailer_enabled(true) .seccomp_enabled(false) .build(); ``` ### Builder Methods | Method | Description | | ------------------------- | -------------------------- | | `new()` | Start from defaults | | `development()` | Start from dev preset | | `standard()` | Start from standard preset | | `maximum()` | Start from max preset | | `jailer_enabled(bool)` | Enable/disable jailer | | `seccomp_enabled(bool)` | Enable/disable seccomp | | `uid(u32)` | Set drop-to UID | | `gid(u32)` | Set drop-to GID | | `new_pid_ns(bool)` | Enable PID namespace | | `new_net_ns(bool)` | Enable network namespace | | `chroot_base(path)` | Set chroot base dir | | `chroot_enabled(bool)` | Enable chroot | | `close_fds(bool)` | Close inherited FDs | | `sanitize_env(bool)` | Sanitize environment | | `env_allowlist(vec)` | Set env allowlist | | `allow_env(var)` | Add to env allowlist | | `resource_limits(limits)` | Set all limits | | `max_open_files(n)` | RLIMIT\_NOFILE | | `max_file_size_bytes(n)` | RLIMIT\_FSIZE | | `max_processes(n)` | RLIMIT\_NPROC | | `max_memory_bytes(n)` | RLIMIT\_AS | | `max_cpu_time_seconds(n)` | RLIMIT\_CPU | | `sandbox_profile(path)` | macOS sandbox profile | | `network_enabled(bool)` | macOS network access | | `build()` | Build SecurityOptions | *** ## ResourceLimits Resource limits for the jailed process. ```rust theme={null} pub struct ResourceLimits { /// Max open file descriptors (RLIMIT_NOFILE) pub max_open_files: Option, /// Max file size in bytes (RLIMIT_FSIZE) pub max_file_size: Option, /// Max number of processes (RLIMIT_NPROC) pub max_processes: Option, /// Max virtual memory in bytes (RLIMIT_AS) pub max_memory: Option, /// Max CPU time in seconds (RLIMIT_CPU) pub max_cpu_time: Option, } ``` *** ## See Also * [Rust SDK Overview](/reference/rust/index) * [Execution](/reference/rust/execution) * [Errors & Metrics](/reference/rust/errors-metrics) * [Architecture - Security](/architecture/security)