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 max_memory(self, bytes: usize) -> Self

Cap total interpreter memory to bytes.

Convenience wrapper over memory_limits that sets max_total_variable_bytes to bytes and clamps max_function_body_bytes to min(bytes, default). Count-based sub-limits (variable count, array entries, function count) stay at their defaults.

Example

let bash = Bash::builder()
    .max_memory(10 * 1024 * 1024)   // 10 MB
    .build();

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 tty(self, fd: u32, is_terminal: bool) -> Self

Configure whether a file descriptor is reported as a terminal by [ -t fd ].

In a sandboxed VFS environment, all FDs default to non-terminal (false). Use this to simulate interactive mode for scripts that check [ -t 0 ] (stdin), [ -t 1 ] (stdout), or [ -t 2 ] (stderr).

let bash = Bash::builder()
    .tty(0, true)  // stdin is a terminal
    .tty(1, true)  // stdout is a terminal
    .build();

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 epoch_offset(self, seconds: i64) -> Self

Apply a constant offset (in seconds) to the real system clock for the date builtin. Use this when scripts need time to advance at real-clock rate but you want to obscure the absolute wall-clock time from the sandbox (timing-correlation resistance).

THREAT[TM-INF-018]: A non-zero offset prevents date from exposing the host’s exact wall-clock time while still letting time-sensitive scripts observe elapsed-time deltas.

fixed_epoch and epoch_offset are mutually exclusive — the last builder call wins.

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 network(self, allowlist: NetworkAllowlist) -> Self

Configure network access for curl/wget builtins.

Network access is disabled by default. Use this method to enable HTTP requests from scripts with a URL allowlist for security.

Security

The allowlist uses a default-deny model:

• Only URLs matching allowlist patterns can be accessed
• Pattern matching is literal (no DNS resolution) to prevent DNS rebinding
• Scheme, host, port, and path prefix are all validated

Example

use bashkit::{Bash, NetworkAllowlist};

// Allow access to specific APIs only
let allowlist = NetworkAllowlist::new()
    .allow("https://api.example.com")
    .allow("https://cdn.example.com/assets");

let bash = Bash::builder()
    .network(allowlist)
    .build();

Warning

Using NetworkAllowlist::allow_all() is dangerous and should only be used for testing or when the script is fully trusted.

pub fn http_handler(self, handler: Box<dyn HttpHandler>) -> Self

Set a custom HTTP handler for request interception.

The handler is called after the URL allowlist check, so the security boundary stays in bashkit. Use this for:

• Corporate proxies
• Logging/auditing
• Caching responses
• Rate limiting
• Mocking HTTP responses in tests

Example

use bashkit::network::HttpHandler;

struct MyHandler;

#[async_trait::async_trait]
impl HttpHandler for MyHandler {
    async fn request(
        &self,
        method: &str,
        url: &str,
        body: Option<&[u8]>,
        headers: &[(String, String)],
    ) -> Result<bashkit::network::Response, String> {
        Ok(bashkit::network::Response {
            status: 200,
            headers: vec![],
            body: b"mocked".to_vec(),
        })
    }
}

let bash = Bash::builder()
    .network(NetworkAllowlist::allow_all())
    .http_handler(Box::new(MyHandler))
    .build();

pub fn bot_auth(self, config: BotAuthConfig) -> Self

Enable transparent request signing for all outbound HTTP requests.

When configured, every HTTP request made by curl/wget/http builtins is signed with Ed25519 per RFC 9421 / web-bot-auth profile. No CLI arguments or script changes needed — signing is fully transparent.

Signing failures are non-blocking: the request is sent unsigned.

Example

use bashkit::{Bash, NetworkAllowlist};
use bashkit::network::BotAuthConfig;

let bash = Bash::builder()
    .network(NetworkAllowlist::new().allow("https://api.example.com"))
    .bot_auth(BotAuthConfig::from_seed([42u8; 32])
        .with_agent_fqdn("bot.example.com"))
    .build();

pub fn log_config(self, config: LogConfig) -> Self

Configure logging behavior.

When the logging feature is enabled, Bashkit can emit structured logs at various levels (error, warn, info, debug, trace) during execution.

Log Levels

• ERROR: Unrecoverable failures, exceptions, security violations
• WARN: Recoverable issues, limit warnings, deprecated usage
• INFO: Session lifecycle (start/end), high-level execution flow
• DEBUG: Command execution, variable expansion, control flow
• TRACE: Internal parser/interpreter state, detailed data flow

Security (TM-LOG-001)

By default, sensitive data is redacted from logs:

• Environment variables matching secret patterns (PASSWORD, TOKEN, etc.)
• URL credentials (user:pass@host)
• Values that look like API keys or JWTs

Example

use bashkit::{Bash, LogConfig};

let bash = Bash::builder()
    .log_config(LogConfig::new()
        .redact_env("MY_CUSTOM_SECRET"))
    .build();

Warning

Do not use LogConfig::unsafe_disable_redaction() or LogConfig::unsafe_log_scripts() in production, as they may expose sensitive data in logs.

pub fn git(self, config: GitConfig) -> Self

Configure git support for git commands.

Git access is disabled by default. Use this method to enable git commands with the specified configuration.

Security

• All operations are confined to the virtual filesystem
• Author identity is sandboxed (configurable, never from host)
• Remote operations (Phase 2) require URL allowlist
• No access to host git config or credentials

Example

use bashkit::{Bash, GitConfig};

let bash = Bash::builder()
    .git(GitConfig::new()
        .author("CI Bot", "ci@example.com"))
    .build();

Threat Mitigations

• TM-GIT-002: Host identity leak - uses configured author, never host
• TM-GIT-003: Host config access - no filesystem access outside VFS
• TM-GIT-005: Repository escape - all paths within VFS

pub fn ssh(self, config: SshConfig) -> Self

Configure SSH access for ssh/scp/sftp builtins.

Example

use bashkit::{Bash, SshConfig};

let bash = Bash::builder()
    .ssh(SshConfig::new()
        .allow("*.supabase.co")
        .default_user("root"))
    .build();

Threat Mitigations

• TM-SSH-001: Unauthorized host access - host allowlist (default-deny)
• TM-SSH-002: Credential leakage - keys from VFS only
• TM-SSH-005: Connection hang - configurable timeouts

pub fn ssh_handler(self, handler: Box<dyn SshHandler>) -> Self

Set a custom SSH handler for transport interception.

Embedders can implement SshHandler to mock, proxy, log, or rate-limit SSH operations. The allowlist check happens before the handler is called.

pub fn sqlite(self) -> Self

Enable embedded SQLite (sqlite/sqlite3 builtins) via Turso.

Registers both names with the default SqliteLimits. The Turso engine is BETA upstream — for security, execution is runtime-gated: set BASHKIT_ALLOW_INPROCESS_SQLITE=1 via builder .env(...) (or export) before invoking sqlite.

Requires the sqlite feature flag. Database files are loaded from / flushed to the virtual filesystem at command boundaries.

Example

let bash = Bash::builder()
    .sqlite()
    .env("BASHKIT_ALLOW_INPROCESS_SQLITE", "1")
    .build();

pub fn sqlite_with_limits(self, limits: SqliteLimits) -> Self

Enable embedded SQLite with custom limits and backend selection.

See BashBuilder::sqlite for details. Use SqliteLimits::backend to switch between the in-memory shim (Phase 1, default) and the VFS-backed adapter (Phase 2).

Example

use bashkit::{SqliteBackend, SqliteLimits};

let bash = Bash::builder()
    .sqlite_with_limits(
        SqliteLimits::default()
            .backend(SqliteBackend::Vfs)
            .max_db_bytes(8 * 1024 * 1024),
    )
    .build();

pub fn typescript(self) -> Self

Enable embedded TypeScript/JavaScript execution via ZapCode with defaults.

Registers ts, typescript, node, deno, and bun builtins. Requires the typescript feature.

Example

let bash = Bash::builder().typescript().build();
bash.exec("ts -c \"console.log('hello')\"").await?;

pub fn typescript_with_limits(self, limits: TypeScriptLimits) -> Self

Enable embedded TypeScript with custom resource limits.

See BashBuilder::typescript for details.

pub fn typescript_with_config(self, config: TypeScriptConfig) -> Self

Enable embedded TypeScript with full configuration control.

Example

use bashkit::{TypeScriptConfig, TypeScriptLimits};
use std::time::Duration;

// Only ts/typescript commands, no node/deno/bun aliases
let bash = Bash::builder()
    .typescript_with_config(TypeScriptConfig::default().compat_aliases(false))
    .build();

// Disable unsupported-mode hints
let bash = Bash::builder()
    .typescript_with_config(TypeScriptConfig::default().unsupported_mode_hint(false))
    .build();

// Custom limits + no compat aliases
let bash = Bash::builder()
    .typescript_with_config(
        TypeScriptConfig::default()
            .limits(TypeScriptLimits::default().max_duration(Duration::from_secs(5)))
            .compat_aliases(false)
    )
    .build();

pub fn typescript_with_external_handler( self, limits: TypeScriptLimits, external_fns: Vec<String>, handler: TypeScriptExternalFnHandler, ) -> Self

Enable embedded TypeScript with external function handlers.

See TypeScriptExternalFnHandler for handler details.

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 builtin_registry(self, registry: BuiltinRegistry) -> Self

Attach a host-owned mutable builtin registry.

Unlike BashBuilder::builtin, entries in a BuiltinRegistry can be inserted and removed after the Bash instance has been built. The registry is host-owned, so its contents survive exec() calls unchanged. This is intended for embedders (FFI bindings, REPLs) that want to register host callbacks at runtime without rebuilding the interpreter.

The registry is consulted during command dispatch after shell functions and POSIX special builtins, but before baked-in builtins — so entries can override baked-in commands of the same name.

The registry handle is Clone; clones share the same underlying storage. Keep a clone after calling this method to retain post-build mutation access.

pub fn extension<E>(self, extension: E) -> Self

where E: Extension,

Register a capability extension.

Extensions contribute a related set of builtins as one unit. Commands registered by an extension follow the same override rules as BashBuilder::builtin: later registrations replace earlier ones with the same name.

Example

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

struct Hello;

#[async_trait]
impl Builtin for Hello {
    async fn execute(&self, _ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        Ok(ExecResult::ok("hello\n".to_string()))
    }
}

struct HelloExtension;

impl Extension for HelloExtension {
    fn builtins(&self) -> Vec<(String, Box<dyn Builtin>)> {
        vec![("hello".to_string(), Box::new(Hello))]
    }
}

let bash = Bash::builder().extension(HelloExtension).build();

pub fn on_exit(self, hook: Interceptor<ExitEvent>) -> Self

Register an on_exit interceptor hook.

Fired when the exit builtin runs. The hook can inspect or modify the ExitEvent, or cancel the exit. Multiple hooks run in registration order.

Example

use bashkit::hooks::{HookAction, ExitEvent};
use std::sync::{Arc, atomic::{AtomicBool, Ordering}};

let exited = Arc::new(AtomicBool::new(false));
let flag = exited.clone();

let bash = bashkit::Bash::builder()
    .on_exit(Box::new(move |event: ExitEvent| {
        flag.store(true, Ordering::Relaxed);
        HookAction::Continue(event)
    }))
    .build();

pub fn before_exec(self, hook: Interceptor<ExecInput>) -> Self

Register a before_exec interceptor hook.

Fires before a script is executed. Can modify the script text or cancel execution entirely.

pub fn after_exec(self, hook: Interceptor<ExecOutput>) -> Self

Register an after_exec interceptor hook.

Fires after script execution completes. Can modify or inspect the output (stdout, stderr, exit code).

pub fn before_tool(self, hook: Interceptor<ToolEvent>) -> Self

Register a before_tool interceptor hook.

Fires before a builtin command is executed. Can modify args or cancel the tool invocation.

pub fn after_tool(self, hook: Interceptor<ToolResult>) -> Self

Register an after_tool interceptor hook.

Fires after a builtin command completes.

pub fn on_error(self, hook: Interceptor<ErrorEvent>) -> Self

Register an on_error interceptor hook.

Fires when the interpreter encounters an error.

pub fn before_http(self, hook: Interceptor<HttpRequestEvent>) -> Self

Register a before_http interceptor hook.

Fires before each HTTP request (after allowlist validation). Can modify the URL/headers or cancel the request.

Example

use bashkit::{Bash, hooks::{HookAction, HttpRequestEvent}};

let bash = Bash::builder()
    .before_http(Box::new(|req: HttpRequestEvent| {
        if req.url.contains("blocked") {
            HookAction::Cancel("blocked by policy".into())
        } else {
            HookAction::Continue(req)
        }
    }))
    .build();

pub fn after_http(self, hook: Interceptor<HttpResponseEvent>) -> Self

Register an after_http interceptor hook.

Fires after each HTTP response is received. Can inspect response status and headers.

pub fn credential(self, pattern: &str, cred: Credential) -> Self

Inject credentials for outbound HTTP requests matching the given URL pattern.

The pattern uses the same matching as NetworkAllowlist (scheme + host + port + path prefix). Injected headers overwrite any existing headers with the same name set by the script, preventing credential spoofing.

The script never sees the real credential — it is injected transparently by a before_http hook after the allowlist check.

Example

use bashkit::{Bash, Credential, NetworkAllowlist};

let bash = Bash::builder()
    .network(NetworkAllowlist::new()
        .allow("https://api.github.com"))
    .credential("https://api.github.com",
        Credential::bearer("ghp_xxxx"))
    .build();
// Scripts can now: curl -s https://api.github.com/repos/foo/bar
// Authorization: Bearer ghp_xxxx is added transparently.

See credential_injection_guide for the full guide.

pub fn credential_placeholder( self, env_name: &str, pattern: &str, cred: Credential, ) -> Self

Inject credentials via a placeholder env var visible to scripts.

Sets environment variable env_name to an opaque placeholder string. When a request to pattern contains the placeholder in any header value, it is replaced with the real credential on the wire.

The placeholder is a random string (bk_placeholder_<hex>) that:

• Cannot be reversed to the real credential
• Is only replaced for requests matching the URL pattern
• Passes most SDK non-empty validation checks

Example

use bashkit::{Bash, Credential, NetworkAllowlist};

let bash = Bash::builder()
    .network(NetworkAllowlist::new()
        .allow("https://api.openai.com"))
    .credential_placeholder("OPENAI_API_KEY",
        "https://api.openai.com",
        Credential::bearer("sk-real-key"))
    .build();
// Scripts see $OPENAI_API_KEY as "bk_placeholder_..." and use it normally.
// The placeholder is replaced with the real key in outbound headers.

See credential_injection_guide for the full guide.

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 mount_lazy( self, path: impl Into<PathBuf>, size_hint: u64, loader: LazyLoader, ) -> Self

Mount a lazy file whose content is loaded on first read.

The loader closure is called at most once when the file is first read. If the file is overwritten before being read, the loader is never called. stat() returns metadata using size_hint without triggering the load.

Example

use bashkit::Bash;
use std::sync::Arc;

let mut bash = Bash::builder()
    .mount_lazy("/data/large.csv", 1024, Arc::new(|| {
        b"id,name\n1,Alice\n".to_vec()
    }))
    .build();

let result = bash.exec("cat /data/large.csv").await?;
assert_eq!(result.stdout, "id,name\n1,Alice\n");

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

Mount a real host directory as a readonly overlay at the VFS root.

Files from host_path become visible at the same paths inside the VFS. For example, if the host directory contains src/main.rs, it will be available as /src/main.rs inside the virtual bash session.

The host directory is read-only: scripts cannot modify host files.

Requires the realfs feature flag.

Example

let bash = Bash::builder()
    .mount_real_readonly("/path/to/project")
    .build();

pub fn mount_real_readonly_at( self, host_path: impl Into<PathBuf>, vfs_mount: impl Into<PathBuf>, ) -> Self

Mount a real host directory as a readonly filesystem at a specific VFS path.

Files from host_path become visible under vfs_mount inside the VFS. For example, mounting /home/user/data at /mnt/data makes /home/user/data/file.txt available as /mnt/data/file.txt.

The host directory is read-only: scripts cannot modify host files.

Requires the realfs feature flag.

Example

let bash = Bash::builder()
    .mount_real_readonly_at("/path/to/data", "/mnt/data")
    .build();

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

Mount a real host directory with read-write access at the VFS root.

WARNING: This breaks the sandbox boundary. Scripts can modify files on the host filesystem. Only use when:

• The script is fully trusted
• The host directory is appropriately scoped

Requires the realfs feature flag.

Example

let bash = Bash::builder()
    .mount_real_readwrite("/path/to/workspace")
    .build();

pub fn mount_real_readwrite_at( self, host_path: impl Into<PathBuf>, vfs_mount: impl Into<PathBuf>, ) -> Self

Mount a real host directory with read-write access at a specific VFS path.

WARNING: This breaks the sandbox boundary. Scripts can modify files on the host filesystem.

Requires the realfs feature flag.

Example

let bash = Bash::builder()
    .mount_real_readwrite_at("/path/to/workspace", "/mnt/workspace")
    .build();

pub fn allowed_mount_paths( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set an allowlist of host paths that may be mounted.

When set, only host paths starting with an allowed prefix are accepted by mount_real_* methods. Paths outside the allowlist are rejected with a warning at build time.

Example

let bash = Bash::builder()
    .allowed_mount_paths(["/home/user/projects", "/tmp"])
    .mount_real_readonly("/home/user/projects/data")  // OK
    .mount_real_readonly("/etc/passwd")                // rejected
    .build();

pub fn readonly_filesystem(self, readonly: bool) -> Self

Make the final virtual filesystem read-only.

This is stronger than mounting real directories read-only: writes to any VFS location fail, including /tmp, redirections, cp, mv, rm, mkdir, and chmod.

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.