Struct ContainerConfig 

pub struct ContainerConfig {

    pub id: String,
    pub name: String,
    pub command: Vec<String>,
    pub context_dir: Option<PathBuf>,
    pub limits: ResourceLimits,
    pub namespaces: NamespaceConfig,
    pub user_ns_config: Option<UserNamespaceConfig>,
    pub hostname: Option<String>,
    pub use_gvisor: bool,
    pub trust_level: TrustLevel,
    pub network: NetworkMode,
    pub context_mode: ContextMode,
    pub allow_degraded_security: bool,
    pub allow_chroot_fallback: bool,
    pub allow_host_network: bool,
    pub proc_readonly: bool,
    pub service_mode: ServiceMode,
    pub rootfs_path: Option<PathBuf>,
    pub rootfs_mode: RootfsMode,
    pub rootfs_overlay: Option<RootfsOverlayConfig>,
    pub egress_policy: Option<EgressPolicy>,
    pub credential_broker: Option<CredentialBrokerConfig>,
    pub credential_broker_token: String,
    pub health_check: Option<HealthCheck>,
    pub readiness_probe: Option<ReadinessProbe>,
    pub secrets: Vec<SecretMount>,
    pub volumes: Vec<VolumeMount>,
    pub workspace: WorkspaceConfig,
    pub home: PathBuf,
    pub provider_configs: Vec<ProviderConfigMount>,
    pub workdir: PathBuf,
    pub environment: Vec<(String, String)>,
    pub derived_environment: Vec<(String, String)>,
    pub process_identity: ProcessIdentity,
    pub config_hash: Option<u64>,
    pub sd_notify: bool,
    pub required_kernel_lockdown: Option<KernelLockdownMode>,
    pub verify_context_integrity: bool,
    pub verify_rootfs_attestation: bool,
    pub seccomp_log_denied: bool,
    pub gvisor_platform: GVisorPlatform,
    pub seccomp_profile: Option<PathBuf>,
    pub seccomp_profile_sha256: Option<String>,
    pub seccomp_mode: SeccompMode,
    pub seccomp_trace_log: Option<PathBuf>,
    pub seccomp_allow_syscalls: Vec<String>,
    pub caps_policy: Option<PathBuf>,
    pub caps_policy_sha256: Option<String>,
    pub landlock_policy: Option<PathBuf>,
    pub landlock_policy_sha256: Option<String>,
    pub hooks: Option<OciHooks>,
    pub pid_file: Option<PathBuf>,
    pub console_socket: Option<PathBuf>,
    pub terminal: bool,
    pub console_size: ConsoleSize,
    pub bundle_dir: Option<PathBuf>,
    pub state_root: Option<PathBuf>,
    pub gpu: Option<GpuPassthroughConfig>,
}

Container configuration

Fields

id: String

Unique container ID (auto-generated 32 hex chars, 128-bit)

name: String

User-supplied container name (optional, defaults to ID)

command: Vec<String>

Command to execute in the container

context_dir: Option<PathBuf>

Context directory to pre-populate (optional)

limits: ResourceLimits

Resource limits

namespaces: NamespaceConfig

Namespace configuration

user_ns_config: Option<UserNamespaceConfig>

User namespace configuration (for rootless mode)

hostname: Option<String>

Hostname to set in UTS namespace (optional)

use_gvisor: bool

Whether to use gVisor runtime

trust_level: TrustLevel

Trust level for this workload

network: NetworkMode

Network mode

context_mode: ContextMode

Context mode (copy or bind mount)

allow_degraded_security: bool

Allow degraded security behavior if a hardening layer cannot be applied

allow_chroot_fallback: bool

Allow chroot fallback when pivot_root fails (weaker isolation)

allow_host_network: bool

Require explicit opt-in for host networking

proc_readonly: bool

Mount /proc read-only inside the container

service_mode: ServiceMode

Service mode (agent vs production)

rootfs_path: Option<PathBuf>

Pre-built rootfs path (Nix store path). When set, this is bind-mounted as the container root instead of bind-mounting host /bin, /usr, /lib, etc.

rootfs_mode: RootfsMode

Mount mode for rootfs_path.

rootfs_overlay: Option<RootfsOverlayConfig>

Prepared overlayfs upper/work directories. Normally populated by the runtime; image run may pre-seed it from an image diff.

egress_policy: Option<EgressPolicy>

Egress policy for audited outbound network access.

credential_broker: Option<CredentialBrokerConfig>

Host-side credential broker that is the sandbox’s only allowed authenticated egress path.

credential_broker_token: String

Random per-container token surfaced to brokered workloads so the host-side broker can authenticate and attribute requests.

health_check: Option<HealthCheck>

Health check configuration for long-running services.

readiness_probe: Option<ReadinessProbe>

Readiness probe for service startup detection.

secrets: Vec<SecretMount>

Secret files to mount into the container.

volumes: Vec<VolumeMount>

Volume mounts to attach to the container filesystem.

workspace: WorkspaceConfig

First-class workspace mount/staging configuration.

home: PathBuf

Private home directory mounted as tmpfs for provider CLIs.

provider_configs: Vec<ProviderConfigMount>

Provider CLI credential/config mounts under home.

workdir: PathBuf

Working directory for the workload process.

environment: Vec<(String, String)>

Environment variables to pass to the container process.

derived_environment: Vec<(String, String)>

Launch-derived environment variables applied at exec time but excluded from ContainerState capture and image commit manifests.

This carries values that are derived from other launch config (e.g. credential-broker proxy env, per-container broker identity) and must not be baked into portable artifacts. The workload still observes them at runtime via the same exec-time env vector as environment.

process_identity: ProcessIdentity

Runtime uid/gid and supplementary groups for the workload process.

config_hash: Option<u64>

Desired topology config hash for reconciliation change detection.

sd_notify: bool

Enable sd_notify integration (pass NOTIFY_SOCKET into container).

required_kernel_lockdown: Option<KernelLockdownMode>

Require the host kernel to be in at least this lockdown mode.

verify_context_integrity: bool

Verify context contents before executing the workload.

verify_rootfs_attestation: bool

Verify rootfs attestation manifest before mounting it.

seccomp_log_denied: bool

Request kernel logging for denied seccomp decisions when supported.

gvisor_platform: GVisorPlatform

Select the gVisor platform backend.

seccomp_profile: Option<PathBuf>

Path to a per-service seccomp profile (JSON, OCI subset format). When set, this profile is used instead of the built-in allowlist.

seccomp_profile_sha256: Option<String>

Expected SHA-256 hash of the seccomp profile file for integrity verification.

seccomp_mode: SeccompMode

Seccomp operating mode.

seccomp_trace_log: Option<PathBuf>

Path to write seccomp trace log (NDJSON) when seccomp_mode == Trace.

seccomp_allow_syscalls: Vec<String>

Additional syscalls to allow beyond the built-in default allowlist. Each entry is a syscall name (e.g. “io_uring_setup”, “sysinfo”). These are merged into the built-in filter; they do NOT replace it.

caps_policy: Option<PathBuf>

Path to capability policy file (TOML).

caps_policy_sha256: Option<String>

Expected SHA-256 hash of the capability policy file.

landlock_policy: Option<PathBuf>

Path to Landlock policy file (TOML).

landlock_policy_sha256: Option<String>

Expected SHA-256 hash of the Landlock policy file.

hooks: Option<OciHooks>

OCI lifecycle hooks to execute at various container lifecycle points.

pid_file: Option<PathBuf>

Path to write the container PID (OCI –pid-file).

console_socket: Option<PathBuf>

Path to AF_UNIX socket for console pseudo-terminal master (OCI –console-socket).

terminal: bool

Run the workload behind a PTY and make it a terminal-attached process.

console_size: ConsoleSize

Initial PTY window size.

bundle_dir: Option<PathBuf>

Override OCI bundle directory path (OCI –bundle).

state_root: Option<PathBuf>

Override root directory for state storage (–root). When set, ContainerStateManager uses this instead of the default.

gpu: Option<GpuPassthroughConfig>

GPU passthrough configuration. When set, selected host GPU device nodes and their minimal driver support files are bound into the container, a cgroup device allowlist is installed, and the seccomp ioctl filter is relaxed for vendor driver ioctls. See spec/gpu-passthrough.md.

Implementations

impl ContainerConfig

pub fn try_new(name: Option<String>, command: Vec<String>) -> Result<Self>

Create a new container config with a random ID.

Panics

Panics if secure random bytes cannot be read from /dev/urandom.

pub fn try_new_with_id( preset_id: Option<String>, name: Option<String>, command: Vec<String>, ) -> Result<Self>

Create a new container config, optionally using a pre-generated ID.

When preset_id is Some, it is used as the container ID instead of generating a new one. This is used by --detach to ensure the outer CLI process and the systemd-managed inner process share the same ID.

pub fn with_rootless(self) -> Self

Enable rootless mode with user namespace mapping

pub fn with_user_namespace(self, config: UserNamespaceConfig) -> Self

Configure custom user namespace mapping

pub fn with_context(self, dir: PathBuf) -> Self

pub fn with_limits(self, limits: ResourceLimits) -> Self

pub fn with_namespaces(self, namespaces: NamespaceConfig) -> Self

pub fn with_hostname(self, hostname: Option<String>) -> Self

pub fn with_gvisor(self, enabled: bool) -> Self

pub fn with_trust_level(self, level: TrustLevel) -> Self

pub fn with_oci_bundle(self) -> Self

Enable OCI bundle runtime path (always OCI for gVisor).

pub fn with_network(self, mode: NetworkMode) -> Self

pub fn with_context_mode(self, mode: ContextMode) -> Self

pub fn with_allow_degraded_security(self, allow: bool) -> Self

pub fn with_allow_chroot_fallback(self, allow: bool) -> Self

pub fn with_allow_host_network(self, allow: bool) -> Self

pub fn with_proc_readonly(self, proc_readonly: bool) -> Self

pub fn with_service_mode(self, mode: ServiceMode) -> Self

pub fn with_rootfs_path(self, path: PathBuf) -> Self

pub fn with_rootfs_mode(self, mode: RootfsMode) -> Self

pub fn with_rootfs_overlay(self, upperdir: PathBuf, workdir: PathBuf) -> Self

pub fn with_egress_policy(self, policy: EgressPolicy) -> Self

pub fn with_credential_broker(self, broker: CredentialBrokerConfig) -> Self

pub fn with_health_check(self, hc: HealthCheck) -> Self

pub fn with_readiness_probe(self, probe: ReadinessProbe) -> Self

pub fn with_secret(self, secret: SecretMount) -> Self

pub fn with_volume(self, volume: VolumeMount) -> Self

pub fn with_workspace(self, workspace: WorkspaceConfig) -> Self

pub fn with_home(self, home: PathBuf) -> Self

pub fn with_provider_config(self, provider_config: ProviderConfigMount) -> Self

pub fn with_workdir(self, workdir: PathBuf) -> Self

pub fn with_env(self, key: String, value: String) -> Self

pub fn with_derived_env(self, key: String, value: String) -> Self

Append a launch-derived env var. Derived env is applied to the workload at exec time but excluded from ContainerState capture and image commit manifests. Use this for values computed from other launch state (broker endpoints, per-container tokens) that must not be baked into portable artifacts.

pub fn with_credential_broker_identity_env(self) -> Self

pub fn with_process_identity(self, identity: ProcessIdentity) -> Self

pub fn with_config_hash(self, hash: u64) -> Self

pub fn with_sd_notify(self, enabled: bool) -> Self

pub fn with_required_kernel_lockdown(self, mode: KernelLockdownMode) -> Self

pub fn with_verify_context_integrity(self, enabled: bool) -> Self

pub fn with_verify_rootfs_attestation(self, enabled: bool) -> Self

pub fn with_seccomp_log_denied(self, enabled: bool) -> Self

pub fn with_gvisor_platform(self, platform: GVisorPlatform) -> Self

pub fn with_seccomp_profile(self, path: PathBuf) -> Self

pub fn with_seccomp_profile_sha256(self, hash: String) -> Self

pub fn with_seccomp_mode(self, mode: SeccompMode) -> Self

pub fn with_seccomp_trace_log(self, path: PathBuf) -> Self

pub fn with_seccomp_allow_syscalls(self, syscalls: Vec<String>) -> Self

pub fn with_caps_policy(self, path: PathBuf) -> Self

pub fn with_caps_policy_sha256(self, hash: String) -> Self

pub fn with_landlock_policy(self, path: PathBuf) -> Self

pub fn with_landlock_policy_sha256(self, hash: String) -> Self

pub fn with_pid_file(self, path: PathBuf) -> Self

pub fn with_console_socket(self, path: PathBuf) -> Self

pub fn with_terminal(self, size: ConsoleSize) -> Self

pub fn with_bundle_dir(self, path: PathBuf) -> Self

pub fn with_state_root(self, root: PathBuf) -> Self

pub fn with_gpu(self, gpu: GpuPassthroughConfig) -> Self

Enable GPU passthrough with the given configuration.

This is the programmatic equivalent of --gpu. See spec/gpu-passthrough.md for the security model.

pub fn validate_strict_agent_mode(&self) -> Result<()>

Validate that strict agent mode invariants are satisfied. Called before container startup when service_mode == StrictAgent.

pub fn validate_production_mode(&self) -> Result<()>

Validate that production mode invariants are satisfied. Called before container startup when service_mode == Production.

pub fn validate_runtime_support(&self) -> Result<()>

Validate runtime-specific feature support.

pub fn apply_runtime_selection( self, runtime: RuntimeSelection, oci: bool, ) -> Result<Self>

Apply runtime selection (native vs gVisor) and OCI bundle mode.

Trait Implementations

impl Clone for ContainerConfig

fn clone(&self) -> ContainerConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ContainerConfig

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

Formats the value using the given formatter.