ortus-boxlang MatchBox — BoxLang Without the JVM
Overview
MatchBox is a native Rust implementation of the BoxLang runtime. It compiles BoxLang source code to a custom bytecode and executes it without any JVM required. MatchBox is ideal for environments where the JVM is unavailable, cold-start time matters, or binary size must be minimal.
MatchBox code is a strict subset of JVM BoxLang. Code written for MatchBox runs on JVM BoxLang, but not vice versa — some JVM-specific APIs are unavailable in MatchBox.
Installation
# Install via the official install script (macOS, Linux)
curl -sSL https://raw.githubusercontent.com/ortus-boxlang/matchbox/master/install/install.sh | bash
# Verify
matchbox --version
Architecture
| Component | Technology | Description |
|---|---|---|
| Parser | Pest PEG (Rust) | Parses BoxLang source to AST |
| Compiler | Rust | Compiles AST to MatchBox bytecode |
| VM | Stack-based bytecode VM (Rust) | Executes bytecode at runtime |
| Targets | native, wasm, js, esp32 |
Output deployment formats |
Compilation Targets
| Target | Command | Output | Use Case |
|---|---|---|---|
native |
matchbox --target native app.bxs |
Executable binary | CLI tools, microservices |
wasm |
matchbox --target wasm app.bxs |
.wasm file |
Edge/FaaS, Wasmtime, containers |
js |
matchbox --target js app.bxs |
.js + .wasm ES module |
Web browsers, Node.js |
esp32 |
matchbox --target esp32 --chip esp32s3 app.bxs |
Firmware | Microcontrollers |
Running Scripts Directly
Without a --target flag, MatchBox interprets and runs BoxLang immediately:
# Run a script directly (JVM-like execution, no output file)
matchbox hello.bxs
# With arguments
matchbox process.bxs --input=data.json --output=result.json
JVM BoxLang vs. MatchBox
| Aspect | JVM BoxLang | MatchBox |
|---|---|---|
| Runtime | JVM (Java 21+) | No JVM — pure Rust |
| Cold start | 300ms–2s | < 10ms |
| Binary size | ~50MB JAR | ~500KB executable |
| Full BoxLang API | ✅ All BIFs | ✅ Core subset |
| Java interop | ✅ Full | ❌ None |
| CFML compat | ✅ (bx-compat-cfml) |
❌ |
| Browser (WASM/JS) | ❌ | ✅ |
| Embedded (ESP32) | ❌ | ✅ |
| Strict subset | Use either | Write for MatchBox, runs on JVM too |
What You Can Build
- CLI tools — Single-file executables with no runtime dependency
- Edge/FaaS functions — Cold-start-sensitive serverless deployments (Fastly, Cloudflare Workers)
- Browser apps — Compile BoxLang logic to WebAssembly or ES modules
- Microservices — Tiny containers with just a
.wasmbinary + scratch image - IoT/embedded — BoxLang on ESP32 microcontrollers via FreeRTOS
One-Way Compatibility
Code written for MatchBox is a strict subset and runs on JVM BoxLang unchanged. This lets you develop locally with JVM BoxLang tooling and deploy anywhere:
# Test with JVM BoxLang locally
boxlang app.bxs
# Deploy as native binary
matchbox --target native app.bxs
# Deploy as WASM
matchbox --target wasm app.bxs
Related Skills
compiled-native-binaries—--target nativesingle binaries + Native Fusion Rust interopwasm-container—--target wasmfor server-side WASM and OCI containerswasm-in-the-browser—--target js/--target wasmfor browsers and Node.jsesp32—--target esp32for microcontroller deployments
Checklist
- Install via the official
install.shscript - Write BoxLang code that avoids JVM-specific APIs (Java interop, full CFML compat)
- Use
matchbox app.bxsto test locally before compiling to a target - Choose the right target for your deployment:
native>wasm>js>esp32 - Remember: MatchBox code runs on JVM BoxLang, but not vice versa