Ratchet: a browser-first WebGPU toolkit for running models in JavaScript

What Ratchet is built for

Ratchet is described as a web-first, cross-platform ML developer toolkit, and the README states the mission plainly: to bring fast, cross-platform GPU-accelerated inference to native and browser targets. The repository is written in Rust under the MIT licence, with the JavaScript surface generated from the Rust crates through WebAssembly.

The philosophy section lists five principles that explain most of the design. Inference only, so the toolkit does not try to train anything. WebGPU and CPU only, so there is no CUDA path and no vendor-specific backend to maintain. First-class quantization support, which is what makes a large model plausible in a browser tab. Lazy computation, so work happens when a result is asked for rather than eagerly. And inplace by default, so buffers are written where they live rather than copied around.

Those five choices together explain why the project looks the way it does. Quantization plus lazy loading plus a WebGPU backend is a design for getting a model to a browser at all, not for maximizing throughput on a datacentre GPU.

The supported model list is short: Whisper, Phi 2 and 3, and Moondream. Gemini 2 2B appears under upcoming models. The README also states that Ratchet is currently in active development, with the engine, more models and compatibility being worked on, and invites contributors to reach out.

The JavaScript API and how model loading works

The README shows the JavaScript surface in a single snippet, and it is the whole usage story for now.

// Asynchronous loading & caching with IndexedDB
let model = await Model.load(AvailableModels.WHISPER_TINY, Quantization.Q8, (p: number) => setProgress(p))
let result = await model.run({ input });

Three things happen in those two lines. The model is loaded asynchronously, and the comment notes that loading and caching use IndexedDB, so a second visit does not refetch the weights. The quantisation level is part of the load call, and Q8 is what the example picks. A progress callback receives a number, which is how a UI shows a download bar.

Then a single run call takes an input object and returns a result. The API is deliberately thin: load once, call run.

Underneath, the Rust side is a Cargo workspace with nine members, including ratchet-core for the engine, ratchet-web for the browser bindings, ratchet-hub for model distribution, ratchet-loader, ratchet-models, ratchet-nn for the neural network layer, ratchet-cli and ratchet-macros. The web bindings are built with wasm-bindgen and js-sys, and the Cargo workspace pins the resolver to 2 with edition 2021.

One dependency detail is worth knowing about, because it explains the shape of the project. The wgpu dependency is not taken from crates.io but from a git branch, with a feature flag named fragile-send-sync-non-atomic-wasm, which points at a fork carrying work for multi-dimensional compute subgroups. The GPU stack is therefore a moving target that the project tracks from a fork rather than a released crate.

Building the WebAssembly packages and the tooling around them

The build is driven by a justfile, which exposes recipes for counting lines in the core crate, installing pyo3, building WebAssembly packages, running browser tests, publishing a preview and pushing an example.

    cd ./crates/ratchet-core && scc -irs

The WebAssembly build wraps wasm-pack and targets the web, with a separate debug recipe that omits the release flag and a test recipe that copies a webdriver config into the crate and runs wasm-pack test headless against a named browser.

    node_modules/.bin/wasm-pack build -s ratchet --target web -d `pwd`/target/pkg/{{CRATE}} --out-name {{CRATE}} ./crates/{{CRATE}} --release

Publishing uses pkg-pr-new rather than a registry, which produces a per-pull-request preview link.

    node_modules/.bin/pkg-pr-new publish --pnpm ./target/pkg/{{CRATE}}

The JavaScript side of that toolchain is minimal, since the repository package.json is a private workspace with only pkg-pr-new and wasm-pack as dev dependencies, pinned through pnpm 8.15.8. There is also a Python layer in the repository, with a requirements.txt that pulls in torch 2.3.0, numpy 1.24.3, the gguf library, mlx on macOS and a fork of the Whisper reference implementation, which the justfile uses when it needs to export libtorch for the native path through the LIBTORCH and DYLD_LIBRARY_PATH environment variables.

Where Ratchet is the wrong tool today

The README is direct about the state of the project: the Rust crate and CLI are listed as coming soon. That single line removes most server-side use cases, because the only supported consumption path is the JavaScript and WebAssembly one.

The second limitation is the model list. Three model families are supported and one is upcoming. If your workload needs a different architecture, there is no path to it yet, and the roadmap link in the README header points at a GitHub project rather than a dated plan, so there is no commitment to judge against.

The third is the GPU dependency. WebGPU is required for the fast path, and the project depends on a forked wgpu branch with a feature explicitly named fragile-send-sync-non-atomic-wasm, which tells you the WASM thread-safety story is not settled. On a browser without WebGPU, you are on the CPU path, and the README does not quote a figure for what that costs. That is the question to ask before committing to a user-facing transcription feature: the difference between a GPU and CPU Whisper run is the difference between a feature people notice and one they wait for.

The fourth is that the examples live in the examples/ directory as ratchet-whisper, ratchet-phi and ratchet-moondream, and the justfile has a recipe that pushes an example subtree split to a separate main branch. That workflow, in which an example is published from a split subtree, is convenient for the maintainer and unusual for anyone expecting a normal application repository.

Licence, maintenance and the cost of following the project

The project is under the MIT licence, with the LICENSE file at the root, and the repository carries an ARCHITECTURE.md, a CONTRIBUTING.md, a rust-toolchain.toml and a config/ directory that holds the webdriver configuration used by the browser test recipe.

The repository is not archived and the last push was on 2026-09-24, so work is ongoing, and the README's own note about active development is consistent with that. There are no GitHub releases on GitHub, so versioning happens through crates and the per-pull-request previews produced by pkg-pr-new.

The cost of depending on this project is that it moves. The wgpu fork, the WASM feature flag in its name, the small model list and the absence of a published crate all point the same way. A team planning to put Ratchet in front of users is taking on the work of tracking a fast-moving engine, and the honest way to plan for that is to pin to a specific commit, treat the browser example as the reference integration, and expect to rebase when the wgpu fork lands upstream changes.

The most realistic evaluation path is the one the README offers: the Hugging Face spaces for Whisper and Phi give a working deployment to look at, and the examples directory holds the code behind them.

Editorial conclusion

Ratchet fits a team that wants speech recognition or a small language model to run client-side in a browser, on WebGPU, without a server round trip, and the JavaScript entry point is small enough to try in an afternoon. It does not fit production work yet, because the README states the project is in active development and the Rust crate and CLI are still to come. Verify the browser and model combination you need against the supported list, which covers Whisper, Phi 2 and 3 and Moondream, with Gemini 2 2B listed as upcoming.

Frequently asked questions

Official sources

1. huggingface/ratchet on GitHub
2. Issues
3. License: MIT
4. README