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 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 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.