Sandbox configuration & limits#

Every Bashkit binding runs scripts inside the same sandbox: an in-memory virtual filesystem, no fork/exec, no host access, and hard resource ceilings. This page covers the knobs that shape that sandbox — resource limits, the filesystem, identity, and the network allowlist. The Rust builder is the reference API; the Python and JavaScript bindings expose the same options through constructor arguments (see the notes at the end).

Resource limits#

Use a named profile when you want one coherent baseline across execution, session memory, the managed VFS, network, and compiled embedded runtimes:

use bashkit::{Bash, ExecutionLimits, ExecutionProfile, ExecutionProfileName};

let profile = ExecutionProfile::builder(ExecutionProfileName::Hardened)
    .execution_limits(
        ExecutionLimits::new()
            .max_commands(5_000) // explicit per-field override
            .max_stdout_bytes(512 * 1024),
    )
    .build()?;

let mut bash = Bash::builder().profile(profile).build();

The closed names are:

Standard — current secure library defaults; the default profile.
Hardened — tighter limits across every resource family. The isolated VFS stays writable under tighter quotas.
Interactive — current REPL intent: relaxed execution/session counters, with secure memory, VFS, network, and runtime defaults unchanged.

Profiles never enable network access. Apply a network allowlist explicitly. Call profile(...) before fine-grained builder methods; later calls are intentional overrides. A custom FileSystem owns its own quota contract and replaces the profile’s managed-VFS limits.

Limits are enforced while the script runs — a script that exceeds one is terminated, not allowed to exhaust the host. Set them with ExecutionLimits:

use bashkit::{Bash, ExecutionLimits};

let limits = ExecutionLimits::new()
    .max_commands(1000)
    .max_loop_iterations(10000)
    .max_function_depth(100);

let mut bash = Bash::builder().limits(limits).build();

The filesystem#

Scripts see a virtual filesystem, never the host disk. Pick a backend and pass it to the builder:

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

let mut bash = Bash::builder()
    .fs(Arc::new(InMemoryFs::new()))
    .build();

See the Virtual filesystem guide for the layering stack (OverlayFs, MountableFs) and the opt-in realfs host-mount backend.

Identity & working directory#

use bashkit::Bash;

let mut bash = Bash::builder()
    .env("HOME", "/home/agent")
    .cwd("/home/agent")
    .username("agent")
    .hostname("sandbox")
    .build();

Network allowlist#

HTTP for curl/wget requires the http_client feature and an explicit allowlist — outbound requests are denied by default:

use bashkit::{Bash, NetworkAllowlist};

let mut bash = Bash::builder()
    .network(NetworkAllowlist::new().allow("https://api.github.com"))
    .build();

See Networking for per-domain control, and Security for the full list of sandbox boundaries.

Other bindings#

The Python and JavaScript bindings take the same options as constructor arguments rather than a builder. For example, in JavaScript:

import { Bash, ExecutionProfile } from "@everruns/bashkit";

const bash = new Bash({
  profile: ExecutionProfile.Hardened,
  cwd: "/home/agent",
  env: { HOME: "/home/agent" },
  maxCommands: 1000,
  maxLoopIterations: 10000,
  maxMemory: 64 * 1024 * 1024,
});

Python exposes the same selector as an enum:

from bashkit import Bash, ExecutionProfile

bash = Bash(profile=ExecutionProfile.Hardened, max_commands=5_000)

The native Node binding and browser-WASM package expose a closed ExecutionProfileName union. C ABI v1 accepts "profile": "hardened" | "standard" | "interactive" in its versioned JSON object and rejects unknown values. Browser WASM has no network or embedded-runtime surface; C ABI v1 has no network/runtime callbacks; profiles only cover capabilities each documented binding supports. Scripted tools always remain logic-only even when a profile is selected.

The Python and Node quickstarts show the per-language constructor options.