---
title: Adding a Runtime
description: End-to-end guide for contributors adding a new language runtime
layout: libdoc_page.liquid
permalink: adding-a-runtime/index.html
eleventyNavigation:
key: Adding a Runtime
order: 6
---
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
```sh
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](/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.