RamShared

Language: Portuguese (Brazil)

RamShared turns idle NVIDIA VRAM into an elastic memory tier for Linux and WSL2. It places compressed RAM first, GPU-backed swap second, and disk swap last. When the GPU needs its budget back, RamShared stops promotion, drains the GPU tier, and releases the allocation.

It is not extra VRAM for games and it does not inspect application names. A game, renderer, browser, video editor, or compute job is simply an external GPU workload. Reclaim decisions use aggregate GPU budget, free-memory, and latency signals.

Current Status

Release: v0.9.0-beta.1, validated on WSL2 Linux 6.6 / 6.18 and Windows 11.

Surface	Status	What that means
Linux/WSL2 cascade	Product path (v0.9.0-beta.1)	CLI, CUDA/NBD tier, zram/disk cascade, diagnostics, and opt-in systemd boot integration are validated.
Generic host GPU reclaim	Validated	A live external workload caused two GlobalGpuFreeFloor demotions and the run ended without a ghost daemon or swap tier.
WSL2 freeze campaign	Validated	Supervised before/action/after rounds completed with watchdog, binary matching, integrity telemetry, and clean terminal state.
Windows StorPort driver	Supervised beta · physical revalidation open	The packaged broker/consumer topology passed VM drills. Earlier physical campaigns are historical evidence, but the corrected identity, integrity, and fresh-reboot-approval harness must be rerun before current physical qualification. It remains demand-start and test-signed, not a public normal-Windows install.
GiB reclaim matrix	Validated	WSL2 1 GiB, WSL2 4 GiB, and calibrated 1 GiB Windows + 3 GiB WSL2 rows passed integrity, reclaim, and clean teardown gates.
Custom-kernel ublk transport	Upstream validated (#41054)	Official WSL kernel contribution submitted with bi-arch builds (x86_64 / ARM64), zero W=1 diagnostics, Sparse C=2 validation, QEMU capability proofs, and tested fork branch.

The status above is intentionally narrower than the architecture. Open claims and the exact evidence needed to close them live in docs/reliability/GAP-REGISTER.md. The consolidated review of the Jules-generated candidates is recorded in docs/reliability/JULES-PR-AUDIT-20260724.md.

Why VRAM-as-Swap in WSL2?

In WSL2, swapping to a virtual disk (ext4 → VHDX → Hyper-V → Windows NTFS) introduces heavy virtualization overhead:

• WSL2 VHDX Disk Swap (4KB QD1 randread p50): ~2,114 µs (~2.1 ms)
• RamShared NBD VRAM Swap (4KB QD1 randread p50): ~326 µs (6.5× faster)
• RamShared ublk Direct io_uring (4KB QD1 randread p50): ~8 µs ± 2 µs (264× faster)

Because swap-in page faults are synchronous, this 3× to 10× reduction in latency eliminates the severe desktop and terminal freezes commonly experienced when memory-hungry workloads exceed physical RAM.

Accelerating Local AI & Heavy Workloads

RamShared provides an elastic cushion for intensive developer workloads:

• Local LLMs & Ollama: Run larger parameter models (8B / 14B / 32B) without OOM crashes when context windows expand.
• PyTorch & CUDA Workloads: Cache host tensors and gradient states in GPU memory with instantaneous retrieval.
• Multi-container Docker Stacks: Prevent container OOM-kills during parallel builds and microservice orchestrations.
• AI Agent Frameworks: Seamless integration and low-latency storage layers for tools such as AgentENV and OverlayBD.

Quick Start

Requirements:

• Linux or WSL2 with an NVIDIA GPU visible through nvidia-smi
• Rust toolchain
• sudo access for block-device and swap lifecycle operations

./scripts/quickstart.sh

sudo ./target/release/ramshared check
sudo ./target/release/ramshared up --vram 1024 --zram 1024
swapon --show
./target/release/ramshared status

Start with a bounded allocation such as 1024 MiB. Keep enough VRAM available for the desktop and other GPU workloads.

Stop through the product lifecycle, never by killing the daemon:

sudo ./target/release/ramshared down

down disables GPU-backed swap before stopping its daemon. This ordering is a data-integrity boundary.

If preflight blocks startup:

sudo ./target/release/ramshared doctor
./target/release/ramshared status --json

Captured JSONL telemetry can be explained locally without sending it to an external service:

./target/release/ramshared diagnose --events /path/to/telemetry.jsonl
./target/release/ramshared diagnose --events /path/to/telemetry.jsonl --json

Memory Cascade

memory pressure
    |
    v
zram (compressed system RAM)
    |
    v
idle GPU memory (elastic tier: NBD or ublk)
    |
    v
disk swap (durable fallback)

The control plane watches GPU headroom and operation latency. When the Windows host or another GPU workload reduces available budget, RamShared:

1. stops promoting pages to the GPU tier;
2. performs a bounded drain of GPU-backed swap;
3. leaves pages in zram or disk swap;
4. releases the CUDA allocation;
5. records the transition and reason in telemetry.

Windows WDDM remains authoritative in WSL2. RamShared reacts to host-visible pressure; it does not promise that opening a particular application instantly or risklessly frees a fixed amount of VRAM.

Safe Operation

• Use ramshared up and ramshared down; do not force-kill ramsharedd while its swap device is active.
• Do not allocate the GPU's full physical capacity. A 6 GiB card cannot safely host 4 GiB + 1 GiB owners plus a 1 GiB reserve and normal desktop usage.
• Run destructive pressure campaigns only through the supervised watchdog harnesses with explicit approval and artifact capture.
• Treat PARTIAL as an evidence state, not a test failure and not a release claim.
• Never initialize, clear, repartition, or format a disk based only on disk number, size, or drive letter.

Desktop Control

On WSLg or desktop Linux:

bash scripts/safety/install-cascade-app.sh
./scripts/safety/cascade-app.sh --gui

The same lifecycle is available without the GUI:

./scripts/safety/cascade-app.sh status
sudo ./scripts/safety/cascade-app.sh start
sudo ./scripts/safety/cascade-app.sh stop

Root authorization is required only at the device and swap boundary.

Opt-in Boot Integration

WSL2 needs systemd enabled in /etc/wsl.conf. After changing that setting, run wsl --shutdown once from Windows.

sudo bash scripts/safety/install-cascade-boot.sh --enable

The unit performs preflight before startup and uses the ordered down path on stop. Remove it with:

sudo bash scripts/safety/uninstall-cascade-boot.sh

Installable Bundle

Build the release bundle with:

scripts/package/build-linux-bundle.sh

The output under artifacts/packages/ contains release binaries, safety scripts, systemd templates, documentation, and SHA256SUMS. Build caches, credentials, VM-local notes, and Windows driver artifacts are excluded. See docs/packaging/INSTALLABLES.md.

The official v0.9.0-beta.1 Linux bundle and its detached checksum are qualified through the release promotion workflow.

Windows Driver Beta

The Windows path is a StorPort virtual miniport backed by GPU memory. Its VM drills pass; corrected physical-host qualification is pending a newly approved campaign. Deployment remains an elevated, supervised beta workflow.

The installed topology has two SCM services:

• RamSharedBroker runs as NT SERVICE\RamSharedBroker and owns logical lease arbitration only;
• RamSharedWinSvc runs as LocalSystem, depends on the broker, and owns CUDA, queue, LUN and safe teardown;
• their daily boundary is the authenticated local named pipe \\.\pipe\RamSharedBroker.v1; no daily TCP listener is installed;
• both are demand-start by default and are switched as one immutable, SHA-256-validated product manifest.

Important boundaries:

• use a disposable VM for routine driver development;
• use a physical host only for an explicitly approved campaign;
• verify the signed package and running binary match before collecting proof;
• refuse installation if the manifest-owned temporary volume letter is already present; never remap an existing host volume;
• mount the temporary LUN under a private directory when possible, not a persistent Explorer drive letter;
• format only an exact RAMSHARE VRAMDISK identity that also matches the expected size and current campaign owner;
• never use Clear-Disk, broad disk-number selection, or physical-disk fallback logic;
• drain any pagefile before backend teardown; surprise removal can cause Windows bugcheck 0x7A.

The calibrated GiB reclaim matrix is closed on the tested RTX 2060 host. Public Windows distribution remains gated on a production-trusted or Microsoft-attested package. Test-signed lab packages are not public releases; see docs/packaging/WINDOWS-DRIVER-DISTRIBUTION.md. Operational install, rollback and recovery steps are in docs/runbooks/windows-autonomous-broker.md.

Performance Evidence

Performance depends on transport, workload, queue depth, host contention, and GPU pressure. The project records those conditions with each result instead of publishing one universal speed.

Representative measurements on the project workstation (NVIDIA RTX 2060 6GB, WSL2 Linux):

Transport / Path	4KB Page Fault Latency (p50)	Throughput (Sequential)	CPU Core Overhead
WSL2 Virtual Disk (VHDX)	~2,114 µs	~3,200 MB/s (NVMe)	Low (DMA)
RamShared NBD (Day-1 MVP)	~326 µs	~2,100 MB/s	~22% (Socket Stack)
RamShared ublk (io_uring)	~8 µs ± 2 µs	~9,600 MB/s	~4% (Ring Buffer)

These are environment-specific observations, not minimum guarantees. Source context and caveats are in docs/BENCHMARKS.md and validation.md.

Architecture

Component	Responsibility
ramshared	CLI: preflight, lifecycle, status, doctor, and diagnosis
ramsharedd	GPU-backed block service (NBD and ublk engine)
ramshared-tier	tier policy and demotion safety
ramshared-cuda	safe wrapper around the NVIDIA/CUDA boundary
ramshared-wsl2d	WSL2 host-pressure coordination and telemetry
ramshared-agent	local host observations and explanations
drivers/windows/ramshared	supervised Windows StorPort beta

Low-level architecture is documented in ARCHITECTURE.md. Changes to locks, DMA, allocation ownership, or kernel contracts require SSDV3 specification and named evidence under docs/specs/.

Documentation

Need	Document
Installation and common questions	docs/FAQ.md
Architecture	ARCHITECTURE.md
Current roadmap	ROADMAP.md
Empirical validation log	validation.md
Open and closed reliability claims	docs/reliability/GAP-REGISTER.md
Benchmark context	docs/BENCHMARKS.md
Lab VM access and inventory policy	docs/labs/HYPERV-VM-ACCESS.md
Contribution rules	CONTRIBUTING.md