Adding a Runtime

End-to-end guide for contributors adding a new language runtime

2026-04-27

Kumar Anirudha

Table of content

1. Create the runtime source
2. Create the build script
3. Register in build-all.sh
4. Update the Dockerfile
5. Update the Rust library
6. Update CI
7. Update the global manifest generator
8. Regenerate and verify
9. Update docs
10. Submit the PR

It seems that your browser JavaScript is disabled, LibDoc is set to fallback mode with reduced features.

Adding a language runtime touches the build pipeline, the Rust library, the CI workflows, and the manifests. Follow every step.

1. Create the runtime source

runtimes/<lang>/
├── <source files>       # The actual program to compile to WASM
└── manifest.json        # Generated by build script

The runtime source should implement a standard set of commands: version, eval, env, echo, cat, ls, write. See runtimes/go/main.go and runtimes/rust/src/main.rs for the expected interface.

2. Create the build script

scripts/build-<lang>.sh. Follow the pattern in scripts/build-go.sh or scripts/build-rust.sh:

Accept source path as argument
Support --version, --output, --no-optimize flags
Compile to WASM targeting WASI Preview 1 (wasip1)
Run wasm-opt with --enable-bulk-memory if available
Copy output to runtimes/<lang>/
Call scripts/generate-metadata.sh to update the manifest

3. Register in build-all.sh

Add a build block to scripts/build-all.sh with an env flag (BUILD_<LANG>) for selective builds.

4. Update the Dockerfile

Add the language's compiler/toolchain to Dockerfile. Match the existing pattern (Go, TinyGo, Rust).

5. Update the Rust library

Add a variant to Language enum in src/runtime.rs
Add as_str(), FromStr, and Display implementations
Add to Language::all() array

6. Update CI

Add a matrix entry in .github/workflows/build-runtimes.yml
The release.yml workflow picks up all runtimes automatically via scripts/build-all.sh

7. Update the global manifest generator

Add a source URL and license to the SOURCES and LICENSES arrays in scripts/generate-global-manifest.sh.

8. Regenerate and verify

just docker-build              # Rebuild Docker image with new toolchain
just docker-build-runtimes     # Build all runtimes
just manifest                  # Regenerate global manifest

9. Update docs

Add a page under docs/runtimes/<lang>.md documenting capabilities, limitations, source link
Update Manifest Format if you introduce new fields

10. Submit the PR

Run just ci first — clippy must pass with zero warnings, format check must be clean, all tests must pass.