VSH

VSH is one low-latency transactional filesystem simulator with two SDK surfaces:

native Rust through the vsh-runtime package (vsh library target),
Python through the vbash PyPI distribution and vsh import package.

Both surfaces execute the same Rust pipeline. Python is a thin PyO3 binding; it does not contain a fallback simulator or committer.

Monty program → immutable snapshot → Rust VirtualFs → canonical diff → policy
              → dependency revalidation → recoverable commit → verified receipt

VSH is not a POSIX shell and never gives Monty a host filesystem mount, subprocess, network, or ambient environment capability.

Python

Install the wheel:

uv add vbash

Run one complete transaction. PREVIEW guarantees that host files are unchanged; AUTO commits only a deterministic native auto-approval.

from vsh import ReceiptDetail, RunMode, RunRequest, Runtime

runtime = Runtime.open("/path/to/workspace")
receipt = runtime.run(
    RunRequest(
        """
from pathlib import Path
text = Path('/workspace/input.txt').read_text()
Path('/workspace/output.txt').write_text(text.upper())
len(text)
""",
        mode=RunMode.AUTO,
        detail=ReceiptDetail.FULL,
    )
)

print(receipt.state, receipt.result, receipt.changes)

The GIL is released while snapshotting, executing Monty, generating the diff, evaluating policy, revalidating dependencies, and committing.

Rust

Until the first registry release, use the workspace package directly:

[dependencies]
vsh-runtime = { path = "crates/vbash", version = "=0.3.0" }

use vsh::{ReceiptDetail, RunMode, RunRequest, Runtime, RuntimeConfig};

fn main() -> Result<(), vsh::VshError> {
    let runtime = Runtime::open(RuntimeConfig::new("/path/to/workspace"))?;
    let receipt = runtime.run(
        RunRequest::new(
            "from pathlib import Path\nPath('/workspace/output.txt').write_text('ok')",
        )
        .with_mode(RunMode::Auto)
        .with_detail(ReceiptDetail::Full),
    )?;
    println!("{:?} {}", receipt.state, receipt.transaction);
    Ok(())
}

Production execution expects the matching vsh-monty-worker executable. Python wheels bundle it; native embedders configure its trusted path through RuntimeConfig::with_worker_path.

MCP

Install the optional adapter and start the stdio server:

uv add "vbash[mcp]"
vsh serve

The server exposes exactly one normal tool, vsh_run. A multi-file operation is one Monty program, one Rust transaction, one policy decision, and one Python-to-Rust call. An auto-approved preview can later be promoted by passing its returned transaction handle with mode="auto"; VSH revalidates dependencies before any mutation.

Auto-approved previews use a bounded process-local fast path and must be promoted by the same live Runtime (or MCP server process). The exact artifact is made durable before reservation and commit. Transactions that require independent approval are durable immediately and survive a runtime restart.

Security and dependency policy

External Rust crates are exact-pinned in the workspace manifest and lockfile.
Unknown, abandoned, yanked, Git-only, wildcard, and unreviewed crates are rejected.
cargo audit and cargo deny are release gates.
The hash-locked optional/development Python graph is a strict pip-audit gate.
Protected paths are denied before names or bytes enter Monty.
Approval binds the exact program, snapshot, read/write dependencies, canonical diff, policy, execution configuration, and intent.
The committer is the only host writer and serializes only same-workspace commit revalidation/mutation; independent runtimes do not share a global lock.
Process-local preview retention is fail-closed and bounded by both artifact count and encoded bytes; it cannot become an unbounded parent-process cache.

See the threat model, guarantees, and dependency record. Upgrade and benchmark details are in the migration guide and performance record. Merge coverage scope and floors are recorded in the coverage contract. The cross-platform build, validation, provenance, and dual-registry order are in the release guide.

Documentation

The detailed Rust, Python, MCP, agent, architecture, security, and benchmark guides are built with the exactly pinned Zensical toolchain:

uv run python scripts/generate_llms_txt.py
uv run zensical serve
uv run zensical build --clean --strict

Start at docs/index.md. The site includes a VSH-specific dark-red design, automatic light/dark palette selection, and a Copy as Markdown action on every page. It also publishes a compact LLM index at /llms.txt and the complete Markdown source corpus at /llms-full.txt, with navigation pages first; CI verifies both generated files are current.

Development

uv sync --frozen --all-groups --extra mcp
cargo fmt --all -- --check
cargo test --workspace --all-targets --locked
cargo llvm-cov --workspace --all-features --all-targets --locked --summary-only \
  --ignore-filename-regex '(vsh-python|vsh-worker)' \
  --fail-under-lines 79 --fail-under-functions 70 --fail-under-regions 81
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
uv run ruff check
uv run ruff format --check
uv run pytest \
  tests/test_native_binding.py tests/test_native_runtime.py tests/test_python_surface.py \
  --cov=src/vsh --cov-branch --cov-report=term-missing --cov-fail-under=100
cargo run --release --locked -p vsh-runtime --example native_benchmark -- \
  --worker "$PWD/.venv/bin/vsh-monty-worker"

License

Apache-2.0

Development Status
- 4 - Beta
Intended Audience
- Developers
Programming Language

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vbash-0.3.0.tar.gz (191.3 kB view details)

Uploaded Aug 29, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vbash-0.3.0-cp314-cp314-win_amd64.whl (6.1 MB view details)

Uploaded Aug 29, 2026 CPython 3.14Windows x86-64

vbash-0.3.0-cp314-cp314-manylinux_2_28_x86_64.whl (6.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

vbash-0.3.0-cp314-cp314-manylinux_2_28_aarch64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.14manylinux: glibc 2.28+ ARM64

vbash-0.3.0-cp314-cp314-macosx_11_0_arm64.whl (5.8 MB view details)

Uploaded Aug 29, 2026 CPython 3.14macOS 11.0+ ARM64

vbash-0.3.0-cp314-cp314-macosx_10_12_x86_64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.14macOS 10.12+ x86-64

vbash-0.3.0-cp313-cp313-win_amd64.whl (6.1 MB view details)

Uploaded Aug 29, 2026 CPython 3.13Windows x86-64

vbash-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl (6.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

vbash-0.3.0-cp313-cp313-manylinux_2_28_aarch64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.13manylinux: glibc 2.28+ ARM64

vbash-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (5.8 MB view details)

Uploaded Aug 29, 2026 CPython 3.13macOS 11.0+ ARM64

vbash-0.3.0-cp313-cp313-macosx_10_12_x86_64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.13macOS 10.12+ x86-64

vbash-0.3.0-cp312-cp312-win_amd64.whl (6.1 MB view details)

Uploaded Aug 29, 2026 CPython 3.12Windows x86-64

vbash-0.3.0-cp312-cp312-manylinux_2_28_x86_64.whl (6.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

vbash-0.3.0-cp312-cp312-manylinux_2_28_aarch64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.12manylinux: glibc 2.28+ ARM64

vbash-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (5.8 MB view details)

Uploaded Aug 29, 2026 CPython 3.12macOS 11.0+ ARM64

vbash-0.3.0-cp312-cp312-macosx_10_12_x86_64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.12macOS 10.12+ x86-64

vbash-0.3.0-cp311-cp311-win_amd64.whl (6.1 MB view details)

Uploaded Aug 29, 2026 CPython 3.11Windows x86-64

vbash-0.3.0-cp311-cp311-manylinux_2_28_x86_64.whl (6.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

vbash-0.3.0-cp311-cp311-manylinux_2_28_aarch64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.11manylinux: glibc 2.28+ ARM64

vbash-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (5.8 MB view details)

Uploaded Aug 29, 2026 CPython 3.11macOS 11.0+ ARM64

vbash-0.3.0-cp311-cp311-macosx_10_12_x86_64.whl (6.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.11macOS 10.12+ x86-64

File details

Details for the file vbash-0.3.0.tar.gz.

File metadata

Download URL: vbash-0.3.0.tar.gz
Upload date: Aug 29, 2026
Size: 191.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for vbash-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`c87a052f350b2fa4254ea9c49cbdfc94c32fb497b7c83a2eadc91b36fa33a677`
MD5	`f4276f9aaa981c9e3eed89487be82d13`
BLAKE2b-256	`7ec0d38663c69665d3fa06e212137ba6112067f74112971fd6f81becacca1085`

Algorithm	Hash digest
SHA256	`6558405d31095da343283a256444c7f4328e9bbf4e74596730d617eaab8e13ef`
MD5	`a57468d3c6ff7a9be54eef0ebfa26048`
BLAKE2b-256	`2ceafbf4fc1777cbff3dc620cd9cef290b10a0a10dd8c665269b483554fcf389`

Algorithm	Hash digest
SHA256	`e54921038dde08798b5a8b68d2ba49fb3766b20b0726f23ca1741fabd74a80ca`
MD5	`ffe30a68963ce8b0d9f4210500d4e511`
BLAKE2b-256	`9145dbf802ce7f2d6bb09bb1d4c22db5131b8ca726461aeff640b6726b940044`

Algorithm	Hash digest
SHA256	`cd9c02b0a60af364c692746742f1f6c82b77e73ffc97ec29e1de88d1a1d772f1`
MD5	`f2487a35db09147311651567bea0d87b`
BLAKE2b-256	`5c7a4f99acec793e8323130838622addbc03a62802db8af8b83b81a68f37cbd1`

Algorithm	Hash digest
SHA256	`68abec8ecc6cd249823f030391839cb50f22b36466ca0b02bc636b70c03fa07f`
MD5	`2dd7d43ea2e4d1861e72a724e80ba8cb`
BLAKE2b-256	`803abb298c9667b4ff3b32d2835beebe63fe91a0b6f7ff2d0407426ba62abba6`

Algorithm	Hash digest
SHA256	`37ff2bbef209656397a1b37afcaecbac1ed96fb59c53d710e4f65f2c59912527`
MD5	`c0587463ad0e682fdd489dd64c0c1ae1`
BLAKE2b-256	`faf8538f91a6d5d9facc205c158a880bda1400185bb3e3f19de7cfee05411a16`

Algorithm	Hash digest
SHA256	`375cccb2def7e54c7d61c3c02b11fbece862c6c5290e7117de51a59f604909b8`
MD5	`8109b0b9f1a40b324c90a2f65b2d1d5e`
BLAKE2b-256	`ecf3b9614484a9651689b86ddb70903e7085503d35ccb8b174b3c79e07cc22b5`

Algorithm	Hash digest
SHA256	`ac2a39942d21f534622736d1f884290b8c04fac543cc78b3a24d1f4a88e105f4`
MD5	`40c811ca20abe5e341b5091a50770d6e`
BLAKE2b-256	`58c5c1ce2b18545c7e3700d6f2f8e7c54d46de28226286af2079292b9abe1c5c`

Algorithm	Hash digest
SHA256	`6e54837600d747301097f9dac0d8452aaf65ff6713b868749df5201875509fea`
MD5	`aa69778afba7f3452c27d5e9472d4d27`
BLAKE2b-256	`e5c1ded88d938722f4236d472512ee853f338bc55d52d3e0e1ee8390eccaa4fc`

Algorithm	Hash digest
SHA256	`9f05fa5e29448b9d65e277c811b3c9648ef177b868475d79066daccbf675149c`
MD5	`5b9ec2459621d37678f0b865273290e4`
BLAKE2b-256	`c6d2e253859763a26794050d238d7c3ff5b19c19ed1e57f63dd63ec73d401b13`

Algorithm	Hash digest
SHA256	`b6b7a4cb1f9b62691879fd601fed06c1aeaf59a450d146beb251c33ae76f2901`
MD5	`488668673b5a80320906e6e386063c4c`
BLAKE2b-256	`f83fd5df16c7fb11c6fcc678b254ff04d334c5acedf1daa8841644931fb0f082`

Algorithm	Hash digest
SHA256	`478e3cf1ad4dc2183ecc331cbf3cbabe2ca82777712ebefcd06d0ad9acf684ca`
MD5	`67e81d7eac7c89b04835554ddef004db`
BLAKE2b-256	`b06d87ad2e131ef08978dcd9a26c74d6c383f6630508ee2c456630e6cc8b4748`

Algorithm	Hash digest
SHA256	`4fe3bb8d9ccff9b11df433ca0ee41c56339367cfb47b4dc09631671c1ccd6436`
MD5	`d8a283032281384a13f5d165f652231f`
BLAKE2b-256	`87e15fb089c463db8f2e3324dc904138c71786df5312c4ba4ff4fc81338b8c4f`

Algorithm	Hash digest
SHA256	`4192b3791f7a53fc6eeee637449cf81a33a9ab8baeaa41982078758ed647a788`
MD5	`027dd38b0a728d407e6c1288e2a4e588`
BLAKE2b-256	`91283ae02f7f3225cfbeb6f6444aee49803d07722ea0702ca59e498d688465cb`

Algorithm	Hash digest
SHA256	`7e58cc6fae32a4ca22943ec89cc2bdeec9079ac2872acba3f895dce67639bc5c`
MD5	`344642fc785e8fe764d4b882049c0d99`
BLAKE2b-256	`d85a8a81d2f16c06e24ef417487246713f14ab0cbff011165fd19e814c165f01`

Algorithm	Hash digest
SHA256	`5090797dc1b64013fa625c6cac1b90a76097c795fd42c9377c65f6ab2192880a`
MD5	`a479782c282bf0a6b3433aca8b32d780`
BLAKE2b-256	`1686c9a7a220600675c02ace83112171f9e2d43413743f910f1fae923883624d`

Algorithm	Hash digest
SHA256	`9916723c4744bc49fa4a6c275bfb1e844b1c79e77becd70d3eb35477a23370a4`
MD5	`b0d8fbaee1c3c98d86c41b0406b28902`
BLAKE2b-256	`6a9bc403b7169a22f65d6422f4ecfd948c7cc72b01f5ea95b962335802b21d42`

Algorithm	Hash digest
SHA256	`e92f8b2feb2613e6cff7dbab6f4426c60115a2d383a0940a4d289d97670ffd59`
MD5	`0b7023833ed8bb26ee4bf7b9d1a4bf18`
BLAKE2b-256	`4c1e834bf2009d0f66b214dced700f802a9a1b61d02e673e28a714ea932ee05a`

Algorithm	Hash digest
SHA256	`e3c556fdf34674aeab206baf2c6400a72eb957739f5da2a90e4f4a1a99989054`
MD5	`fa0d56aba88877733762d5cd6618ea86`
BLAKE2b-256	`0becbf1602962b2c80178e6d83afc924530c73f3c00bebebda0b775337d99a43`

Algorithm	Hash digest
SHA256	`a9d23f7dcd7d8dc6707da31258aa0b2d16678a6719e42bd0156a28bd00bea670`
MD5	`a0d83b1ee7758d3e524a279e2d17a2f2`
BLAKE2b-256	`9a0c377c0312db90f435e35c312f61341c609ddaad5c952976bddf65e233486a`

Algorithm	Hash digest
SHA256	`d4d5d4050fbfa7726ddc43bd2971714a6a2643c69e2fbb61977d89ea0fcf1cfb`
MD5	`a4024dc54e589ad3118ed72dbffef6c9`
BLAKE2b-256	`446d375fc776604994c89ea08cb64242545e51bbbfa74e137ec6cbd3f2d45081`

vbash 0.3.0

VSH

Python

Rust

MCP

Security and dependency policy

Documentation

Development

License

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata