Struct KernelConfig 

pub struct KernelConfig {

    pub name: String,
    pub vfs_mode: VfsMountMode,
    pub cwd: PathBuf,
    pub skip_validation: bool,
    pub interactive: bool,
    pub ignore_config: IgnoreConfig,
    pub output_limit: OutputLimitConfig,
    pub allow_external_commands: bool,
    pub latch_enabled: bool,
    pub trash_enabled: bool,
    pub nonce_store: Option<NonceStore>,
    pub initial_vars: HashMap<String, Value>,
    pub request_timeout: Option<Duration>,
    pub kill_grace: Duration,
    pub vfs_budget_bytes: Option<u64>,
    pub overlay: bool,
}

Configuration for kernel initialization.

Fields

name: String

Name of this kernel (for identification).

vfs_mode: VfsMountMode

VFS mount mode — controls how local filesystem is exposed.

cwd: PathBuf

Initial working directory (VFS path).

skip_validation: bool

Whether to skip pre-execution validation.

When false (default), scripts are validated before execution to catch errors early. Set to true to skip validation for performance or to allow dynamic/external commands.

interactive: bool

When true, standalone external commands inherit stdio for real-time output.

Set by script runner and REPL for human-visible output. Not set by MCP server (output must be captured for structured responses).

ignore_config: IgnoreConfig

Ignore file configuration for file-walking tools.

output_limit: OutputLimitConfig

Output size limit configuration for agent safety.

allow_external_commands: bool

Whether external command execution (PATH lookup, exec, spawn) is allowed.

When true (default), commands not found as builtins are resolved via PATH and executed as child processes. When false, only kaish builtins and backend-registered tools are available.

Security: External commands bypass the VFS sandbox entirely — they see the real filesystem, network, and environment. Set to false when running untrusted input.

latch_enabled: bool

Enable confirmation latch for dangerous operations (set -o latch).

When enabled, destructive operations like rm require nonce confirmation. Can also be enabled at runtime with set -o latch or via KAISH_LATCH=1.

trash_enabled: bool

Enable trash-on-delete for rm (set -o trash).

When enabled, small files are moved to freedesktop.org Trash instead of being permanently deleted. Can also be enabled at runtime with set -o trash or via KAISH_TRASH=1.

nonce_store: Option<NonceStore>

Shared nonce store for cross-request confirmation latch.

When Some, the kernel uses this store instead of creating a fresh one. This allows nonces issued in one MCP execute() call to be validated in a subsequent call. When None (default), a fresh store is created.

initial_vars: HashMap<String, Value>

Variables to populate the root scope with at construction, all marked for export to child processes.

The kernel itself is hermetic — it never reads std::env::vars() — so frontends that want OS-env passthrough (REPL, MCP) populate this from std::env::vars(). Embedders that want isolation pass nothing (or only the keys they curate).

request_timeout: Option<Duration>

Default per-request timeout. When Some, every execute_with_options call without an explicit ExecuteOptions::timeout uses this duration. When elapsed, the kernel cancels the request, kills any external children with the configured grace, and returns exit code 124.

None means no default timeout — only explicit per-call timeouts apply.

kill_grace: Duration

Grace period between SIGTERM and SIGKILL when killing an external child on cancellation or timeout.

Defaults to 2 seconds. Set to Duration::ZERO to escalate immediately to SIGKILL. Long-shutdown processes (databases, etc.) may need more.

vfs_budget_bytes: Option<u64>

Cap on memory-resident bytes across all kernel-owned MemoryFs mounts.

One shared ByteBudget (labeled "vfs-memory") is created at kernel construction and handed to every MemoryFs the kernel builds in setup_vfs (Passthrough /v; Sandboxed / and /v; NoLocal /, /tmp, /v). Writes that would exceed the cap fail loudly with StorageFull — an in-band error a model reads and adapts to; fail loud over quietly eating RAM.

Why MCP is bounded by default: each execute() call creates a fresh kernel (see server/execute.rs), so the 64 MiB cap is per-call, not per-session. Embedders that know their workload needs more opt out with without_vfs_budget() or raise the cap with with_vfs_budget(bytes) — protection on by default, opt out knowingly. All other profiles default to None (unbounded).

Follows the same pattern as OutputLimitConfig: MCP bounded, rest unbounded.

overlay: bool

Enable copy-on-write overlay mode (opt-in).

When true, the primary local filesystem mount is wrapped in an OverlayFs so writes are virtual — the lower layer is never touched. Use kaish-vfs status/diff/commit/reset to inspect and manage the overlay transaction.

Passthrough: / becomes OverlayFs over LocalFs::read_only("/"). Sandboxed{root}: the {root} mount becomes OverlayFs over LocalFs::read_only(root); the /tmp and XDG runtime mounts stay as real LocalFs (real writes escape the transaction — see docs/kaish-overlayfs.md for the escape-hatch inventory). NoLocal: incompatible — construction fails loudly (everything is already virtual; an overlay adds no value and no lower layer to wrap). with_backend: incompatible — the embedder controls the VFS; the kernel cannot wrap it without bypassing the embedder’s semantics.

Not default-on for MCP: each execute() call gets a fresh kernel, making the overlay a per-call transaction — kaish-vfs commit must run in the same call as the writes, or the transaction is discarded on drop. Frontends (REPL, MCP) expose --overlay as an explicit opt-in flag.

Implementations

impl KernelConfig

pub fn transient() -> Self

Create a transient kernel config (sandboxed, for temporary use).

pub fn named(name: &str) -> Self

Create a kernel config with the given name (sandboxed by default).

pub fn repl() -> Self

Create a REPL config with passthrough filesystem access.

Native paths like /home/user/project work directly. The cwd is set to the actual current working directory.

pub fn mcp() -> Self

Create an MCP server config with sandboxed filesystem access.

Local filesystem is accessible at its real path (e.g., /home/user), but sandboxed to $HOME. Paths outside the sandbox are not accessible through builtins. External commands still access the real filesystem — use .with_allow_external_commands(false) to block them.

VFS memory is bounded at 64 MiB per execute() call by default (MCP creates a fresh kernel per call). Raise or remove with with_vfs_budget / without_vfs_budget.

pub fn mcp_with_root(root: PathBuf) -> Self

Create an MCP server config with a custom sandbox root.

Use this to restrict access to a subdirectory like ~/src.

VFS memory is bounded at 64 MiB per execute() call by default. Raise or remove with with_vfs_budget / without_vfs_budget.

pub fn isolated() -> Self

Create a config with no local filesystem (memory only).

Complete isolation: no local filesystem and external commands are disabled. Useful for tests or pure sandboxed execution.

pub fn with_vfs_mode(self, mode: VfsMountMode) -> Self

Set the VFS mount mode.

pub fn with_cwd(self, cwd: PathBuf) -> Self

Set the initial working directory.

pub fn with_skip_validation(self, skip: bool) -> Self

Skip pre-execution validation.

pub fn with_interactive(self, interactive: bool) -> Self

Enable interactive mode (external commands inherit stdio).

pub fn with_ignore_config(self, config: IgnoreConfig) -> Self

Set the ignore file configuration.

pub fn with_output_limit(self, config: OutputLimitConfig) -> Self

Set the output limit configuration.

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

Set whether external command execution is allowed.

When false, commands not found as builtins produce “command not found” instead of searching PATH. The exec and spawn builtins also return errors. Use this to prevent VFS sandbox bypass via external binaries.

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

Enable or disable confirmation latch at startup.

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

Enable or disable trash-on-delete at startup.

pub fn with_nonce_store(self, store: NonceStore) -> Self

Use a shared nonce store for cross-request confirmation latch.

Pass a NonceStore that outlives individual kernel instances so nonces issued in one MCP execute() call can be validated in subsequent calls.

pub fn with_var(self, name: impl Into<String>, value: Value) -> Self

Add a single initial variable; marked exported when the kernel boots.

Repeated calls add (last write wins on key collision).

pub fn with_initial_vars(self, vars: HashMap<String, Value>) -> Self

Replace the entire initial-vars map. All entries are marked exported.

pub fn with_vars(self, vars: HashMap<String, Value>) -> Self

Extend the initial-vars map with the given entries (last write wins).

pub fn with_request_timeout(self, timeout: Duration) -> Self

Set the default per-request timeout (kernel-wide).

Each execute_with_options call without an explicit timeout uses this. On elapsed, the kernel cancels and returns exit code 124.

pub fn with_kill_grace(self, grace: Duration) -> Self

Set the SIGTERM-to-SIGKILL grace period for child kills.

pub fn with_vfs_budget(self, bytes: u64) -> Self

Cap VFS memory-resident bytes at bytes across all kernel-owned MemoryFs mounts. A shared ByteBudget labeled "vfs-memory" is created at kernel construction and passed to every MemoryFs the kernel builds (see setup_vfs and with_backend).

Writes that would exceed the cap fail loudly with StorageFull — an in-band error a model reads and adapts to; fail loud over quietly eating RAM. Use without_vfs_budget to remove the cap entirely.

pub fn without_vfs_budget(self) -> Self

Remove the VFS memory budget — all MemoryFs mounts are unbounded.

Use when the caller knows the workload and the default 64 MiB cap (set by KernelConfig::mcp) is too conservative.

pub fn with_overlay(self, overlay: bool) -> Self

Enable or disable copy-on-write overlay mode.

When true, the primary local filesystem mount is wrapped in an OverlayFs so writes are virtual — the lower layer is never touched. Incompatible with VfsMountMode::NoLocal (fails loudly at construction) and with_backend kernels (same — the embedder controls the VFS).

Trait Implementations

impl Clone for KernelConfig

fn clone(&self) -> KernelConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KernelConfig

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

Formats the value using the given formatter.

impl Default for KernelConfig

fn default() -> Self

Returns the “default value” for a type.