Struct BashBuilder 

pub struct BashBuilder { /* private fields */ }

Implementations

impl BashBuilder

pub fn fs(self, fs: Arc<dyn FileSystem>) -> Self

Set a custom filesystem.

pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set an environment variable.

pub fn cwd(self, cwd: impl Into<PathBuf>) -> Self

Set the current working directory.

pub fn limits(self, limits: ExecutionLimits) -> Self

Set execution limits.

pub fn session_limits(self, limits: SessionLimits) -> Self

Set session-level resource limits.

Session limits persist across exec() calls and prevent tenants from circumventing per-execution limits by splitting work.

pub fn memory_limits(self, limits: MemoryLimits) -> Self

Set per-instance memory limits.

Controls the maximum variables, arrays, and functions a Bash instance can hold. Prevents memory exhaustion in multi-tenant use.

pub fn trace_mode(self, mode: TraceMode) -> Self

Set the trace mode for structured execution tracing.

• TraceMode::Off (default): No events, zero overhead
• TraceMode::Redacted: Events with secrets scrubbed
• TraceMode::Full: Raw events, no redaction

pub fn on_trace_event(self, callback: TraceCallback) -> Self

Set a real-time callback for trace events.

The callback is invoked for each trace event as it occurs. Requires trace_mode to be set to Redacted or Full.

pub fn username(self, username: impl Into<String>) -> Self

Set the sandbox username.

This configures whoami and id builtins to return this username, and automatically sets the USER environment variable.

pub fn hostname(self, hostname: impl Into<String>) -> Self

Set the sandbox hostname.

This configures hostname and uname -n builtins to return this hostname.

pub fn fixed_epoch(self, epoch: i64) -> Self

Set a fixed Unix epoch for the date builtin.

THREAT[TM-INF-018]: Prevents date from leaking real host time. When set, date returns this fixed time instead of the real clock.

pub fn history_file(self, path: impl Into<PathBuf>) -> Self

Enable persistent history stored at the given VFS path.

History entries are loaded from this file at startup and saved after each exec() call. The file is stored in the virtual filesystem.

pub fn builtin(self, name: impl Into<String>, builtin: Box<dyn Builtin>) -> Self

Register a custom builtin command.

Custom builtins extend bashkit with domain-specific commands that can be invoked from bash scripts. They have full access to the execution context including arguments, environment, shell variables, and the virtual filesystem.

Custom builtins can override default builtins if registered with the same name.

Arguments

• name - The command name (e.g., “psql”, “kubectl”)
• builtin - A boxed implementation of the Builtin trait

Example

use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};

struct Greet {
    default_name: String,
}

#[async_trait]
impl Builtin for Greet {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let name = ctx.args.first()
            .map(|s| s.as_str())
            .unwrap_or(&self.default_name);
        Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
    }
}

let bash = Bash::builder()
    .builtin("greet", Box::new(Greet { default_name: "World".into() }))
    .build();

pub fn mount_text( self, path: impl Into<PathBuf>, content: impl Into<String>, ) -> Self

Mount a text file in the virtual filesystem.

This creates a regular file (mode 0o644) with the specified content at the given path. Parent directories are created automatically.

Mounted files are added via an OverlayFs layer on top of the base filesystem. This means:

• The base filesystem remains unchanged
• Mounted files take precedence over base filesystem files
• Works with any filesystem implementation

Example

use bashkit::Bash;

let mut bash = Bash::builder()
    .mount_text("/config/app.conf", "debug=true\nport=8080\n")
    .mount_text("/data/users.json", r#"["alice", "bob"]"#)
    .build();

let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=true\nport=8080\n");

pub fn mount_readonly_text( self, path: impl Into<PathBuf>, content: impl Into<String>, ) -> Self

Mount a readonly text file in the virtual filesystem.

This creates a readonly file (mode 0o444) with the specified content. Parent directories are created automatically.

Readonly files are useful for:

• Configuration that shouldn’t be modified by scripts
• Reference data that should remain immutable
• Simulating system files like /etc/passwd

Mounted files are added via an OverlayFs layer on top of the base filesystem. This means:

• The base filesystem remains unchanged
• Mounted files take precedence over base filesystem files
• Works with any filesystem implementation

Example

use bashkit::Bash;

let mut bash = Bash::builder()
    .mount_readonly_text("/etc/version", "1.2.3")
    .mount_readonly_text("/etc/app.conf", "production=true\n")
    .build();

// Can read the file
let result = bash.exec("cat /etc/version").await?;
assert_eq!(result.stdout, "1.2.3");

// File has readonly permissions
let stat = bash.fs().stat(std::path::Path::new("/etc/version")).await?;
assert_eq!(stat.mode, 0o444);

pub fn build(self) -> Bash

Build the Bash instance.

If mounted files are specified, they are added via an OverlayFs layer on top of the base filesystem. This means:

• The base filesystem remains unchanged
• Mounted files take precedence over base filesystem files
• Works with any filesystem implementation

Example

use bashkit::{Bash, InMemoryFs};
use std::sync::Arc;

// Works with default InMemoryFs
let mut bash = Bash::builder()
    .mount_text("/config/app.conf", "debug=true\n")
    .build();

// Also works with custom filesystems
let custom_fs = Arc::new(InMemoryFs::new());
let mut bash = Bash::builder()
    .fs(custom_fs)
    .mount_text("/config/app.conf", "debug=true\n")
    .mount_readonly_text("/etc/version", "1.0.0")
    .build();

let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=true\n");

Trait Implementations

impl Default for BashBuilder

fn default() -> BashBuilder

Returns the “default value” for a type.