Virtual filesystem#

Every Bashkit script runs against an in-memory virtual filesystem (VFS), not the host disk. cat, ls, cp, redirections, mkdir — they all work exactly as a script expects, but the bytes live in memory and disappear when the interpreter is dropped. Path traversal like ../../../etc/passwd is normalised away, and symlinks are stored but never followed. The host is invisible by default; you grant access deliberately, never by accident.

This is the foundation of the security model: there is no real filesystem to escape to unless you mount one.

The layering stack#

A Bash instance composes its filesystem from layers. Each layer wraps the one below it, so you can stack read-only enforcement, text mounts, and host mounts over an in-memory base — and swap mounts at runtime.

<g font-size="11" fill="#404040">
  <text x="338" y="42">Bash::mount() / unmount()</text>
  <text x="338" y="94">readonly_filesystem()</text>
  <text x="338" y="146">mount_text()</text>
  <text x="338" y="198">mount_real_*_at()</text>
  <text x="338" y="250">Bash::new()</text>
</g>
<g stroke="#0a1636" stroke-opacity="0.25">
  <line x1="180" y1="60" x2="180" y2="68"/>
  <line x1="180" y1="112" x2="180" y2="120"/>
  <line x1="180" y1="164" x2="180" y2="172"/>
  <line x1="180" y1="216" x2="180" y2="224"/>
</g>

Two-layer trait model#

Internally the VFS splits raw storage from POSIX semantics:

Layer	Trait	Responsibility
Backend	`FsBackend`	Raw storage operations and failure-atomic mutations
POSIX	`FileSystem` / `PosixFs`	POSIX-like validation (no duplicate names, type-safe ops, parent-dir rules)

If you want a custom backend (a database, object store, key-value store), implement the small FsBackend and wrap it in PosixFs — the POSIX checks come for free. Implement FileSystem directly only when you need full control over semantics.

PosixFs validates operations before delegating them, but it cannot make a raw backend mutation atomic. A custom FsBackend must make failed write, copy, and rename operations failure-atomic; a direct FileSystem has the same obligation for write_file, copy, and rename. Errors must leave source and destination entries, bytes, types, and reported usage unchanged. A wrapper moving entries between independent backends must restore the previous destination on failure or reject the move before mutation, usually with ErrorKind::CrossesDevices.

verify_filesystem_requirements() is a structural smoke check for root access and path normalization. It does not mutate the filesystem or certify failure atomicity, symlink behavior, quota accounting, or error normalization; custom adapter tests remain responsible for those invariants.

Built-in implementations#

Implementation	Purpose
InMemoryFs	Default (`Bash::new()`). `HashMap`-backed, thread-safe, no persistence. Seeds `/`, `/tmp`, `/home`, `/home/user`, `/dev`.
OverlayFs	Copy-on-write over another filesystem, with whiteout tracking for deletes.
MountableFs	Mount multiple filesystems at different paths (longest-prefix match). Always the outermost layer, enabling live mounts.
NamespaceFs	Compose a static visible tree from rebased filesystem subtrees, with per-mount access and synthetic ancestors.
ReadOnlyFs	Delegates reads, denies every mutation with `PermissionDenied` — even writes to `/tmp`, `cp`, `mv`, `rm`, `chmod`. For inspection-only sessions.
RealFs (`realfs` feature)	Direct access to a host directory. Read-only (safe) or read-write (dangerous); path traversal blocked by canonicalisation + root-prefix checks.

Mounting host directories#

Real host access is opt-in and read-only by default. The realfs feature adds builder and CLI entry points:

use bashkit::Bash;

let mut bash = Bash::builder()
    .mount_real_readonly("/host/data")        // visible read-only inside the VFS
    .build();

bashkit --mount-ro /host/data:/data -c 'ls /data'   # read-only
bashkit --mount-rw /host/out:/out  -c 'echo hi > /out/f'  # writable (dangerous)

To freeze a session — including in-memory writes — wrap it with readonly_filesystem().

Composing a static namespace#

NamespaceFs creates an intentionally bounded path tree instead of a fallback root plus live mounts. Each source may be rebased and independently read-only or read-write:

use bashkit::{Bash, FileSystem, InMemoryFs, NamespaceFs};
use std::path::Path;
use std::sync::Arc;

let repository = Arc::new(InMemoryFs::new());
repository.mkdir(Path::new("/repo/src"), true).await?;
repository.write_file(Path::new("/repo/src/lib.rs"), b"source").await?;
let output = Arc::new(InMemoryFs::new());

let namespace = NamespaceFs::builder()
    .mount_readonly_from("/src", repository, "/repo/src")?
    .mount_readwrite("/build", output)?
    .build();
let mut bash = Bash::builder().fs(Arc::new(namespace)).build();
assert_eq!(bash.exec("cat /src/lib.rs").await?.stdout, "source");

Nested targets use longest-prefix precedence. Missing ancestors and mount points are visible as directories. Files and symlinks can be copied across mounts; cross-mount rename reports a typed cross-device error because copy-delete is not atomic.

Host-backed filesystem (JS)#

The wasm bindings accept an fs object, so scripts run directly against storage you own — a Durable Object, an OPFS handle, IndexedDB — instead of the in-memory VFS. Nothing is copied in or diffed back out: every read and write during the run is a call into your object.

const bash = new Bash({ cwd: "/workspace", fs: myHost });
const r = await bash.execute("grep -rl TODO . | head -5");

Seven methods are required — read, write, mkdir, remove, stat, readDir, exists — and each may return its value directly or as a Promise. append, copy, rename, and chmod are optional and synthesized from the required primitives when omitted. Your host implements raw storage only; POSIX semantics (parent-directory checks, “is a directory”, symlink resolution) are enforced above it. Throw an Error carrying a code (ENOENT, EEXIST, EACCES, …) so bash reports the failure the way a real shell does.

Two contract notes:

execute() only. A host call can suspend the interpreter, and executeSync cannot await — it reports the suspension instead of blocking.
files is rejected alongside fs. Seeding writes through the VFS synchronously, which a promise-returning host can never satisfy.

The host object is the security boundary and is yours to scope (mount root, allowlist, read-only): paths are normalized before any host call, so traversal cannot select a path you did not expose, but the sandbox reaches whatever the object exposes. Reads and writes bypass the in-memory quotas. See @everruns/bashkit-wasm for the full method table and error-code list.

Special files and symlinks#

/dev/null is handled at the interpreter level (not the filesystem), so a custom backend can’t intercept it. /dev/urandom / /dev/random return bounded random data.
Symlinks are stored but never followed — this closes symlink-escape (TM-ESC-002) and symlink-loop DoS (TM-DOS-011).

Binding parity#

Every language binding exposes the same concepts, so the model is identical from Rust, Python, and Node:

files:  { "/path": "content" }                 # writable in-memory text files
mounts: [{ host_path, vfs_path?, writable? }]  # real FS (read-only by default)
readonly_filesystem: bool                       # deny all VFS mutations after setup

The wasm bindings additionally accept fs — an embedder-supplied filesystem that replaces the in-memory VFS entirely. See Host-backed filesystem (JS) above.