ortus-boxlang BoxLang WASM Containers (Server-Side)
Overview
MatchBox can compile BoxLang source to WebAssembly (WASM) for server-side execution. WASM containers run without a JVM and are sandboxed by design, making them ideal for edge deployments, FaaS, and microservices in minimal OCI containers.
This skill covers server-side WASM (Wasmtime, WasmEdge, OCI containers). For browser/Node.js WASM, see the
wasm-in-the-browserskill.
Compiling to WASM
# Compile to .wasm
matchbox --target wasm my_service.bxs
# Output: my_service.wasm
Running with Wasmtime
# Install Wasmtime
curl https://wasmtime.dev/install.sh -sSf | bash
# Run the WASM module
wasmtime my_service.wasm
# With filesystem access (needed for file I/O)
wasmtime --dir=. my_service.wasm
# With network access (experimental WASI sockets)
wasmtime --wasi-modules=experimental-wasi-sockets my_service.wasm
# Pass CLI arguments
wasmtime my_service.wasm -- --input=data.json --debug
Running with WasmEdge
# Install WasmEdge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
# Run
wasmedge my_service.wasm
# With WASI filesystem
wasmedge --dir=. my_service.wasm
OCI Container (Minimal Docker Image)
Build a Docker image containing only the WASM binary — results in an extremely small image:
# Multi-stage: compile with MatchBox, package as WASM container
FROM ghcr.io/ortus-boxlang/matchbox:latest AS builder
WORKDIR /build
COPY my_service.bxs .
RUN matchbox --target wasm my_service.bxs
# Final image: scratch + WASM binary only
FROM scratch
COPY --from=builder /build/my_service.wasm /app.wasm
ENTRYPOINT ["/app.wasm"]
Run with a WASM-capable container runtime (e.g., containerd + WasmEdge shim):
docker run --runtime=io.containerd.wasmedge.v1 myimage:latest
WASI Capabilities
WASM modules are sandboxed by default. Grant capabilities explicitly:
| Wasmtime Flag | Capability |
|---|---|
--dir=. |
Filesystem access (current dir) |
--dir=/data |
Filesystem access (specific dir) |
--env KEY=VALUE |
Environment variables |
--wasi-modules=experimental-wasi-sockets |
Network socket access |
# Full capability example
wasmtime \
--dir=/var/data \
--env DATABASE_URL=... \
--wasi-modules=experimental-wasi-sockets \
my_service.wasm
Edge Deployments
MatchBox WASM output targets WASI and can run on edge platforms:
Fastly Compute
fastly compute build --source my_service.wasm
fastly compute deploy
Cloudflare Workers (WASI)
# Use Cloudflare's WASM worker with WASI support
wrangler deploy --compatibility-flags=nodejs_compat
Use Cases
| Scenario | Why WASM |
|---|---|
| Serverless/FaaS | Near-zero cold start, no JVM |
| Edge computing | Runs close to users, sandboxed |
| Microservices | FROM scratch images < 1MB |
| Multi-tenant SaaS | Strong WASM sandboxing per tenant |
| Plugin systems | Load and unload WASM modules at runtime |
Comparison: WASM vs Native Binary
--target wasm |
--target native |
|
|---|---|---|
| Portable | ✅ Any WASM runtime | ❌ Single platform |
| Sandboxed | ✅ WASI sandbox | ❌ Full OS access |
| Cold start | < 10ms | < 5ms |
| File/network | Explicit grants | Full OS |
| Edge platforms | ✅ Fastly, CF Workers | ❌ |
| Docker image | FROM scratch + runtime shim |
FROM scratch only |
Checklist
- Use
matchbox --target wasm service.bxsto produce the.wasmfile - Test locally with
wasmtime --dir=. service.wasmbefore deploying - Grant only the capabilities the service needs (
--dir,--env, sockets) - Build
FROM scratchOCI images for minimal container footprint - Use multi-stage Docker builds: compile with MatchBox, ship only the WASM
- For edge deploys, verify WASI compatibility with the target platform (Fastly, Cloudflare)