WASM Container

Learn how to run BoxLang in a WASM container using MatchBox

WASM Container Deployment

MatchBox WASM binaries can be run as standalone server-side workloads using WASM-native runtimes like Wasmtime, WasmEdge, or inside minimal OCI containers using the WASM OCI image spec.

This deployment model is ideal for:

• Serverless / FaaS — minimal cold-start, no OS dependencies.
• Edge computing — run BoxLang logic at the network edge (Fastly Compute, Cloudflare Workers via WASI).
• Microservices — tiny, hermetically isolated workloads without a full OS stack.

---

Compiling for WASM/WASI

Use --target wasm to produce a raw .wasm binary:

matchbox --target wasm my_service.bxs
# Produces: my_service.wasm

The resulting binary contains the MatchBox VM core and your compiled BoxLang bytecode in a custom WASM section. It has no external JS dependencies and can be loaded by any WASM runtime that supports the WASI preview1 interface.

---

Running with Wasmtime

Wasmtime is the reference WASI runtime. Install it and run your binary directly:

# Install Wasmtime (macOS / Linux)
curl https://wasmtime.dev/install.sh -sSf | bash

# Run your app
wasmtime my_service.wasm

Grant filesystem access if your app reads or writes files:

wasmtime --dir=. my_service.wasm

Grant network access (Wasmtime 14+):

wasmtime --wasi-modules=experimental-wasi-sockets my_service.wasm

---

Running with WasmEdge

WasmEdge is optimized for cloud-native and microservice workloads:

# Install WasmEdge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash

# Run
wasmedge my_service.wasm

---

Docker / OCI Container

MatchBox WASM binaries can be run inside minimal OCI containers. Because the WASM runtime handles everything, the container image needs only the binary itself — no OS, no shell, no libc.

Example Dockerfile

FROM scratch

COPY my_service.wasm /my_service.wasm

ENTRYPOINT ["/my_service.wasm"]

Build and run with a WASM-capable container runtime:

docker build -t my-boxlang-service .
docker run --runtime=io.containerd.wasmtime.v1 my-boxlang-service

Note: Standard Docker uses runc by default. To run WASM containers you need a WASM-compatible runtime shim such as containerd-shim-wasmtime or Docker Desktop's built-in WASM support.

Docker Desktop (Built-in WASM Support)

Docker Desktop 4.15+ includes native WASM support via docker run:

docker run --runtime=io.containerd.wasmtime.v1 \
    --platform=wasi/wasm32 \
    my-boxlang-service

Pushing to a Registry

WASM OCI images can be pushed to any OCI-compatible registry:

docker push ghcr.io/your-org/my-boxlang-service:latest

---

Limitations

Feature	WASM Container	Notes
Java interop	❌ Not supported	No JNI in WASM
Native Fusion	✅ Partial	Rust interop is valid for any Rust code that can run in WASM
DOM / js.* APIs	❌ Not available	JS interop requires a browser context
Filesystem access	✅ Via WASI	Requires runtime --dir grants
Network access	⚠️ Experimental	WASI sockets are in preview
sleep() / async	✅	Cooperative fiber scheduler works in WASI