VSH

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

native Rust through the vsh crate, backed by vsh-runtime,
Python through the vsh-python 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.

Special thanks to Artyom Pavlov for generously donating the vsh crate name to this project.

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 vsh-python

Run one complete transaction. PREVIEW does not apply changes to user workspace files; the host runtime may still persist bounded transaction/storage artifacts. 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.

Pydantic AI

Install the exact-pinned optional integration:

uv add "vsh-python[pydantic-ai]"

from pydantic_ai import Agent
from vsh.pydantic_ai import VshCapability

capability = VshCapability("/path/to/workspace")
agent = Agent("openai:gpt-5", capabilities=[capability])

The capability contributes the ten native vsh_* filesystem operations plus vsh_run for atomic multi-step work. Every call executes in a virtual snapshot first. Policy-controlled changes commit exactly once or return pending_approval; no internal LLM judge is created implicitly.

For explicitly configured model review, attach a CommitJudge through hook_handler=judge.hook_handler. It evaluates canonical changes, before/after content, effects and intent together. A valid approval can directly commit pending work; native hard-deny and stale checks remain enforced. Review returns actionable feedback to the main agent.

Rust

[dependencies]
vsh = "=0.5.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.

Active-snapshot filesystem functions

VSH injects ten bounded vsh_* functions into each Monty program: read, write, list, make directory, remove, move, copy, glob, literal search and exact text patch. They share the same copy-on-write snapshot as pathlib, so earlier virtual writes are visible to later calls without creating a nested runtime or crossing MCP.

files = vsh_glob('**/*.toml', path='/workspace/services', max_results=101)
assert len(files) <= 100, 'split this migration into reviewed batches'
for path in files:
    assert vsh_patch(path, 'timeout = 5', 'timeout = 15', count=1) == 1
{'updated': len(files)}

MCP

Install the optional adapter and start the stdio server:

uv add "vsh-python[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.

Performance

On the dated macOS arm64 release-profile matrix, VSH 0.4.0 lowers median latency by roughly 25–30% for 10,000-file discovery/glob and 5,050-entry removal workloads. The whole benchmark harness reports about 19% less CPU time. Small-call variance remains, and sampled process-tree RSS does not establish a repeatable memory reduction. See the protocol, complete results and caveats.

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, dependency policy, current performance report, and coverage contract.

Package names

Existing declarations may install vbash==0.5.0 from PyPI or depend on vbash = "=0.5.0" from crates.io. Both names are implementation-free mirrors of the exact matching VSH release. New projects should use vsh-python and vsh directly; Python code continues to write import vsh either way.

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 the VSH documentation. The site includes a Venus-inspired palette, automatic light/dark 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

vsh_python-0.5.0.tar.gz (262.4 kB view details)

Uploaded Sep 5, 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.

vsh_python-0.5.0-cp314-cp314-win_amd64.whl (6.5 MB view details)

Uploaded Sep 5, 2026 CPython 3.14Windows x86-64

vsh_python-0.5.0-cp314-cp314-manylinux_2_28_x86_64.whl (6.9 MB view details)

Uploaded Sep 5, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

vsh_python-0.5.0-cp314-cp314-manylinux_2_28_aarch64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.14manylinux: glibc 2.28+ ARM64

vsh_python-0.5.0-cp314-cp314-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded Sep 5, 2026 CPython 3.14macOS 11.0+ ARM64

vsh_python-0.5.0-cp314-cp314-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.14macOS 10.12+ x86-64

vsh_python-0.5.0-cp313-cp313-win_amd64.whl (6.5 MB view details)

Uploaded Sep 5, 2026 CPython 3.13Windows x86-64

vsh_python-0.5.0-cp313-cp313-manylinux_2_28_x86_64.whl (6.9 MB view details)

Uploaded Sep 5, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

vsh_python-0.5.0-cp313-cp313-manylinux_2_28_aarch64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.13manylinux: glibc 2.28+ ARM64

vsh_python-0.5.0-cp313-cp313-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded Sep 5, 2026 CPython 3.13macOS 11.0+ ARM64

vsh_python-0.5.0-cp313-cp313-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.13macOS 10.12+ x86-64

vsh_python-0.5.0-cp312-cp312-win_amd64.whl (6.5 MB view details)

Uploaded Sep 5, 2026 CPython 3.12Windows x86-64

vsh_python-0.5.0-cp312-cp312-manylinux_2_28_x86_64.whl (6.9 MB view details)

Uploaded Sep 5, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

vsh_python-0.5.0-cp312-cp312-manylinux_2_28_aarch64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.12manylinux: glibc 2.28+ ARM64

vsh_python-0.5.0-cp312-cp312-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded Sep 5, 2026 CPython 3.12macOS 11.0+ ARM64

vsh_python-0.5.0-cp312-cp312-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.12macOS 10.12+ x86-64

vsh_python-0.5.0-cp311-cp311-win_amd64.whl (6.5 MB view details)

Uploaded Sep 5, 2026 CPython 3.11Windows x86-64

vsh_python-0.5.0-cp311-cp311-manylinux_2_28_x86_64.whl (6.8 MB view details)

Uploaded Sep 5, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

vsh_python-0.5.0-cp311-cp311-manylinux_2_28_aarch64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.11manylinux: glibc 2.28+ ARM64

vsh_python-0.5.0-cp311-cp311-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded Sep 5, 2026 CPython 3.11macOS 11.0+ ARM64

vsh_python-0.5.0-cp311-cp311-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.11macOS 10.12+ x86-64

File details

Details for the file vsh_python-0.5.0.tar.gz.

File metadata

Download URL: vsh_python-0.5.0.tar.gz
Upload date: Sep 5, 2026
Size: 262.4 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 vsh_python-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`7dc83d458fbe7f920c9ea3fea606fe1fdad396c35adeb0ffa4de233762edc215`
MD5	`868aeabf8aa08320d41cded81b3fd26f`
BLAKE2b-256	`f211641fa0c977794bea9a86477b34c358ff2133ae426f1112f40e07e37b1d24`

Algorithm	Hash digest
SHA256	`f6a54cfe1e4c98820cac6ed15dd2a171c5afb8a8b18e587c0850cbb73b66c7a1`
MD5	`0367b7c51d0b6eaa60e75a4e441a436e`
BLAKE2b-256	`36b1fa059c500528734c14a84c5ebe2459ab3c3e1a806e5f0b4a1856ff80cce7`

Algorithm	Hash digest
SHA256	`7f2a971e052862c97ce9ef3a95fd65a9a16a7a571e20bb2a325246cff8fa57c7`
MD5	`cd0259a9b106269f297fc190b0b04881`
BLAKE2b-256	`d658eb1db8d873cfcc0af4faf8b4cad6f29d5f72a64309ada909a00de8072cb9`

Algorithm	Hash digest
SHA256	`cab7a608dae15c125077ce869adfaa3c0b8fb1c79738d136249630c794735855`
MD5	`78d5196398184d1dfd51ca736d1f301a`
BLAKE2b-256	`3a6db3f523970c039eb55060ad8805ca3e44b28ec2b994e748be365135136d4a`

Algorithm	Hash digest
SHA256	`c4fc2fb6858bef3d1b0f9e03b4ecf68d533dcb9edafcf95446c357878697a782`
MD5	`1b32531df4deaee9a8797212276b2fa5`
BLAKE2b-256	`2d833912556fc889163a2c7356955223d8013a24994185bddbf5b6d169ab5d54`

Algorithm	Hash digest
SHA256	`825170a8c5b1e0c234ed28a57237165edfb5d42eea349be70655bb104e1486a0`
MD5	`2ef28fa851c340c2db51b3ae17b7ef18`
BLAKE2b-256	`feaaaf5d89145ce4b0c60b9535c64abed10044a13617ad2b5cf5af841327babf`

Algorithm	Hash digest
SHA256	`33230436ab0eab42f29367bc6f5d1b06ce04cd37f1954ab549cd855139c30957`
MD5	`702801b384498556b6e32af1368821c2`
BLAKE2b-256	`fd6aa4c5f8face5005e68cce2459cbcec53d5ae119c1b51156f1d38d3c64a930`

Algorithm	Hash digest
SHA256	`ee41ec3dd66d7df5ba09279d0c99b9ddc6e535b11eaf9964451217d6d11a439c`
MD5	`407a8eb4a24b448f4fd0007c90e65b58`
BLAKE2b-256	`bfe84fe7095245ebe6b7ad001318ec1a541cb6899647f4c19d80470322fa3ea3`

Algorithm	Hash digest
SHA256	`9e2c6874226964910ccf645e83587f98c0b79ae844f8638431c07596aac62e88`
MD5	`b1c3147aad1ac698a11fb805810af427`
BLAKE2b-256	`fe266a854abf593c7e92ee44c1aaa80dbbea7e3797073818f340a6d42ae42811`

Algorithm	Hash digest
SHA256	`1ee5bdd54b6c7ceb338356d0e5e3d3bba31958053e29bbf3fcf8cd9fe3b055c7`
MD5	`432b71df2edb158117f3e0a8302a43a0`
BLAKE2b-256	`f5a73e30f364ef2d5a669d9161d967a1ff3864414839ee1cb41488163f0d6d5d`

Algorithm	Hash digest
SHA256	`08f2670583e93ba28de0a6931b0959182c5471f993adf0eae4838f9169f56512`
MD5	`6f55236ed662c0ef9769f077739a4bac`
BLAKE2b-256	`64d317d99f677e8bf55498340da35214d3294c651f879210630a2b81af94478f`

Algorithm	Hash digest
SHA256	`4dd8ba2845cefeef5e5b27f0f25c9e670f00317aa47b267a2d915665daa033e9`
MD5	`1201e9df3237c3823df2f0dda3c1d80f`
BLAKE2b-256	`63065828eccf2fb104657c1f45ccc5353d20a06fec8f091d3ccec75069345643`

Algorithm	Hash digest
SHA256	`44fd527b8e001bc15f893dc68a8db79b3d14ddadbf343dda5cd8875ebd55a271`
MD5	`df39df288764734bba97a7adf6443f5d`
BLAKE2b-256	`054663c66e0ce73c9edc67ca8d21cc77c69b327ba44e64c5c17c6eb9a403fc26`

Algorithm	Hash digest
SHA256	`db6e11a403aff8ac111acf8c0c8c18fa92a890d9b8ec0337535ea86396450304`
MD5	`6c92f8839b4d153bfa8855ef4d86dcb0`
BLAKE2b-256	`82852d08d1ecdfc2b624bdbba3362e3e04ae62e2c7594c0efbbb0e14cc9e4e5f`

Algorithm	Hash digest
SHA256	`f6fde9dd151bb9444d819181f6b0bdf6dc04c2bd9446611a8c2af62a9e885c9c`
MD5	`a589b942ee5307537b555f707f2315b1`
BLAKE2b-256	`5f14bc5648fb57e45b65092f0fd23b3b97ccc0c6d90d053bd4bd0c465787248b`

Algorithm	Hash digest
SHA256	`515e6c0dfb9a2d924a81c7cb2aec7acde765cfd55f1b3383d893350e1f91ae10`
MD5	`1da0bca883fb92f8f95807cd70a198e0`
BLAKE2b-256	`2d8eafaf841965251d1bd6c3420c404ed4e325d3ccbea14fdbc6837ad1b5c28b`

Algorithm	Hash digest
SHA256	`b16d608bac9ce6e7f908e60d3a6303f83f7533a161e1e9e87e8632a3d7c1b5f2`
MD5	`41fd3b153a657443e2af6ede973c2a43`
BLAKE2b-256	`5a6252de128b90280093968fb82ec4857feb696593e3272e9b89b14c47dd2ccd`

Algorithm	Hash digest
SHA256	`9ed1878e1c842744e4a0aeff8f1d307dc6c91881ef07a764a80c936554d6746a`
MD5	`4a607a9236b94b1f20ad496b0d8bda69`
BLAKE2b-256	`3d359a90e97ee1d3b3594c8c99cc2608e15e92faeaaafd6a194975e71f2626d1`

Algorithm	Hash digest
SHA256	`ed853bd09c358845330b90cee1a926aeaeba4efc4c87b4d6a3f51840c8e45ccc`
MD5	`b4ff80ad25066965b9768b0810914976`
BLAKE2b-256	`d9bbee6a848b071042aa8dd7bfce1b2a868f78cad7eaa2d7fcbdbfe59f12140e`

Algorithm	Hash digest
SHA256	`9871037c5d328ff9616054f1fb1fb3ca6e0fd029938d51a5d1b82b440fb8c0c3`
MD5	`a14e66dd176780c31864fd7cff3fd3f4`
BLAKE2b-256	`4a9c8e6106cbab56716dba563cc04f74d03aea9e2e9614771696de39ca3d61ee`

Algorithm	Hash digest
SHA256	`c76939ee966c173ae3a1dd91d819be378415a897f7c8925a614913c03743fb5d`
MD5	`d39acef52ebee2c1d191b204bd19da57`
BLAKE2b-256	`3157dd19f4e4091d35757efc82fd5c34b4e98c89554aed9fc194aeda79e8697b`

vsh-python 0.5.0

VSH

Python

Pydantic AI

Rust

Active-snapshot filesystem functions

MCP

Performance

Security and dependency policy

Package names

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