# WASM Container

## WASM Container Deployment

MatchBox WASM binaries can be run as standalone server-side workloads using WASM-native runtimes like [Wasmtime](https://wasmtime.dev/), [WasmEdge](https://wasmedge.org/), 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:

```bash
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](https://wasmtime.dev/) is the reference WASI runtime. Install it and run your binary directly:

```bash
# 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:

```bash
wasmtime --dir=. my_service.wasm
```

Grant network access (Wasmtime 14+):

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

***

### Running with WasmEdge

[WasmEdge](https://wasmedge.org/) is optimized for cloud-native and microservice workloads:

```bash
# 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

```dockerfile
FROM scratch

COPY my_service.wasm /my_service.wasm

ENTRYPOINT ["/my_service.wasm"]
```

Build and run with a WASM-capable container runtime:

```bash
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`](https://github.com/containerd/runwasi) 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`:

```bash
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:

```bash
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                    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://boxlang.ortusbooks.com/getting-started/running-boxlang/wasm-container.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.