Cosmos: a parametric generator for ergonomic mechanical keyboards

A generator rather than a keyboard model

Cosmos describes itself as the most adaptable generator for ergonomic mechanical keyboards, and the difference between a generator and a model is the whole idea. A model is a fixed artefact, a single board with a fixed layout that you either take or leave. A generator takes parameters, a layout, a case style, a set of parts, and produces a keyboard that is derived from them, which means a family of keyboards from one definition and the ability to change one thing and regenerate. The project is a SvelteKit application with a TypeScript core, the 3D preview runs on three.js through the threlte components, and it computes the geometry and then builds the model in OpenCascade. The audience is split in two. There are hobbyists who want a keyboard that fits their hands and cannot find one commercially, and there are small operations who want to produce a keyboard without employing a mechanical engineer. There is also a third group, contributors, which is why the README tells you that if you cannot program but know CAD, there is a tutorial for helping improve the models.

Open core, with three paid features

Cosmos is released under an open-core model, and the README is precise about the split. 95% of the generator is free and open source, while the Pro features, which are rounded edges, the stilts model and wrist rests, are not. That is a specific and unusual boundary, because it means the shape of the finished product is partly closed. Rounded edges in particular are the feature that decides whether a case looks manufactured or looks printed, and wrist rests are the ergonomic component that a lot of users care about most. So the free part of the generator gets you a working, customisable keyboard, and the paid part is what turns it into something you would want on a desk. The commercial side of the project is the Cosmos site itself, and the licensing question for anyone who wants to reuse the code is answered by the licence section, which is worth reading carefully because it is layered.

Geometry and modelling are deliberately separate

The contributing guide names the three files to touch if you want to change how generated keyboards look, and that short list is the clearest statement of the architecture in the repository. The files are src/lib/worker/geometry.ts, src/lib/worker/cachedGeometry.ts and src/lib/worker/model.ts. Rendering in Cosmos is split into two parts, which the README calls geometrical calculations, determining where parts go, and modelling operations, building the 3D model in OpenCascade. The first two files perform the geometrical calculations, with cachedGeometry acting as a higher-level wrapper over functions in geometry.ts, and model.ts is responsible for all 3D modelling operations. The practical value of that split is that layout questions, which are about positions and angles, stay in TypeScript and testable, while the expensive solid modelling stays in the CAD kernel. It also means the same layout can feed different outputs, since the repository pre-generates STEP and GLB files for the generator, in files kept under src/model_gen.

Running the generator with Bun and make

The recommended local setup starts by cloning the repository and installing Bun, and the README gives the reason: Bun has built-in TypeScript and path mapping support. Node.js 22 or later is the alternative, and the trade-off is stated plainly, because Cosmos uses a custom ESM loader with Node, which is more difficult to debug when things go wrong, while the WASM build scripts are more reliable under Node than under Bun. With the toolchain in place the build step is a make target. The Makefile shows what those targets look like, with each keyboard family having its own protobuf to TypeScript step:

target/proto/cosmos.ts: src/proto/cosmos.proto
	$(NPX) protoc --ts_out target --proto_path src $<

The quickstart target compiles and builds the necessary files, and the dev target starts a dev server. After that you visit the beta route on the local dev server, which the README points at as http://localhost:5173/beta. The dev documentation is the place to look if you want to compile the docs or make a production build. On Windows the same make targets run through bun make, or through npm run nodemake if Bun is not installed, and the project ships its own cross-platform make runner implemented as a TypeScript script. The Docker route exists too, with docker compose up in the project root, and a SKIP_MAKE_FILES setting in the .env file that avoids re-running the make scripts on rebuild, which the README notes reduces build time once the target files and docs already exist. The author's own advice is not to use Docker unless you have to, because it adds a lot of complexity, and Cosmos is designed to run with a single installation of Bun, plus Python if you want local docs.

The build is protobuf, OpenSCAD and cloned assets

The Makefile shows what a build of this kind involves. There is a target for OpenSCAD that runs a download script, and separate targets that run protoc with the TypeScript output flag to turn .proto files into TypeScript, one per keyboard family, manuform, cuttleform, lightcycle and cosmos. Other targets generate editor type declarations and the cosmos structures file, and the keycaps and microcontroller targets clone external repositories, the KeyV2 repository on its choc branch and the PseudoMakeMeKeyCapProfiles project, with the latter's libraries unpacked from a zip in the same directory. The Makefile also chooses between Bun and Node for the build, detecting Bun with a shell command and falling back to a Node invocation with a loader import. Two more dependencies on the JavaScript side give a sense of the stack: the replicad library, which is a JavaScript binding to OpenCascade, and a fork of the manifold-3d geometry library published as @rianadon/manifold-3d, alongside a custom WASM build of the library that the README mentions as more reliable under Node.

Hand scanning, and the plan to open it up

A second feature sits alongside the generator: hand scanning, with the code under src/routes/scan and most of the processing in lib/hand.ts. The dependency list shows how it is done, with the MediaPipe hands package for hand detection and the browser camera as the input. The scanning feature is the one with a stated product plan. The author is planning to build out an API to make it easy for users to share their scanned hand data with other keyboard related websites, and asks maintainers of such sites to get in touch if they want to show visitors how a keyboard fits their hand. In the meantime, the code is usable, with the explicit condition that you abide by the AGPL-3.0 licence terms. That condition is the reason the licence section of the README needs reading before you build on the scanning code, because a hand scanning site of your own would be a derivative work in the AGPL sense, and the author is being direct about the terms rather than vague about them.

Three licences in one repository

The licence arrangement is layered, and each layer has a different term. All code is licensed under AGPL-3.0, which is the copyleft licence with the network clause, and it is the right one to read if you plan to run a modified Cosmos as a service. All STEP models under the src/assets folder are licensed under CC0 1.0, which is a public domain dedication, so those files can be reused without attribution obligations. All documentation is licensed under CC BY-SA 4.0, which requires attribution and share-alike on derivative documentation. And all other assets and images are copyrighted and may not be reused without permission, so the images in the repository are not free even though the models next to them are. On the maintenance side, the repository publishes no GitHub releases, the manifest version reads 0.0.1 with the package marked private, and the last push to the main branch was on 2026-07-20. The project's own site and documentation live at ryanis.cool/cosmos.

Editorial conclusion

Cosmos suits a keyboard enthusiast or a small manufacturer who wants a working ergonomic layout without modelling every part by hand, and who is comfortable with a build that pulls in OpenSCAD, protobuf and a generated asset chain. It is the wrong tool if you need a one-off custom plate, since the generator is built for parameterised families rather than single designs, and the paid features are exactly the ones that make a finished product look finished. Before building on it, read the three licence paragraphs, because the code, the STEP models and the documentation carry three different licences, and confirm the Pro features you need are not the ones you would otherwise have to reimplement.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. rianadon/Cosmos-Keyboards on GitHub