Choosing a runtimealpha
Should I use the CLI, the server, the browser, or the on-chain builder?
moxzi is one compiler and four places to run it or its output: the moxzi CLI, the moxzid server, the moxzi-web browser package, and the compiler deployed as an IC canister. The constraint that makes the choice low-stakes is byte identity — the same compiler wasm runs in all four, and an artifact built anywhere deploys anywhere — so picking a runtime is a question of trust, latency and hosting, not of semantics.
The decision table#
| Use case | Use | Why | The one thing that will bite you |
|---|---|---|---|
| Local iteration | moxzi CLI | sub-second hello-world; the AOT cache reloads the 7.8 MB compiler in ~0.03 s instead of JIT-ing it | first run on a machine pays ~1 s of JIT and says (JIT) under --timings; a big project needs --stack-budget raised or it takes minutes instead of seconds |
| CI | moxzi CLI, or the Docker image | one binary, no dfx, no moc, no replica; provenance hash printed on every build so you can assert it | compiler.wasm/linker.wasm are not built by cargo build — CI must cache or ship them, and a job without them fails at build time, not at install time |
| Hosting a demo | moxzid | --web <actor> serves the actor's http_request interface at the root, so an actor is simply a website; state is durable across kill -9 | a non-loopback bind without --auth-token is refused at startup, and the /site/… gateway is open by design while the ops endpoints are not |
| Teaching / playground | moxzi-web | actors and the compiler run in the tab; nothing to install, state persists to IndexedDB, deadlineMs kills a student's infinite loop | a page cannot interrupt a running wasm call — deadlineMs and HTTPS outcalls both require worker: true, and outcalls additionally require COOP/COEP headers |
| Trustless build provenance | on-chain builder (--remote) | the artifact is produced by a compiler anyone can inspect, from sources anyone can hash; the CLI still links locally | the escrow is real money and builds serialize — one canister is one job queue — and uploaded source sits in the canister's VFS where operators can read it |
| Running an app off-chain | moxzid | IC message semantics without a subnet: rollback, timers, cycles, actor-to-actor calls, HTTPS outcalls, crash durability | no certificates off-chain, single node, one shared token; anything depending on certified data needs the real IC |
How the four relate#
The CLI is the one everything else assumes. moxzid and moxzi-web host the wasm the CLI produced; the on-chain builder replaces the compile, not the run. Nothing here is a replica emulator with consensus: moxzid and moxzi-web run one node with IC message semantics, which is the part a program can observe.
| Property | CLI | moxzid | moxzi-web | on-chain builder |
|---|---|---|---|---|
| Produces wasm | yes | no | in-tab compile, byte-identical | yes |
| Runs actors | no | yes | yes | n/a |
| Instruction metering | n/a | yes (--instruction-limit, default 40e9) | opt-in (meter: true), same default limit; unmetered, preemption is wall-clock | n/a |
| Certificates | n/a | no | no | n/a |
| Durability | n/a | snapshot + write-ahead log | IndexedDB (autosave, saveAll/loadAll) | n/a |
| Costs money | no | no | no | yes, when the operator has configured payment |
Choosing between local and on-chain builds#
A local build and an on-chain build of the same sources produce the same bytes. That means the on-chain builder buys exactly one thing: an artifact whose production someone else can check. If nobody is going to check, build locally.
local moxzi build | --remote <url> --canister <id> | |
|---|---|---|
| Speed | seconds | minutes, and it queues behind other jobs |
| Cost | free | escrow at the CMC's live ICP↔XDR rate; settlement charges 3× actual use and refunds the rest |
| Who vouches for the bytes | you | a canister anyone can audit |
| Source privacy | total | uploaded files sit in the canister VFS; builds from mops tags upload nothing |
| Linking | local | still local — a deliberate, documented gap in the trust chain |
On a fresh deployment payment is inert: the canister compiles for free and says so. It never silently charges.
Things you cannot do#
- You cannot get certified responses off-chain. A certificate is a subnet threshold signature and neither
moxzidnor a browser tab has a subnet. A forged one would be verified and believed, which is worse than none, so it is not offered. - You cannot meter instructions in a browser. Message and creation fees are charged everywhere; per-instruction limits are enforced in
moxzid(wasmtime fuel) and on the IC only. - You cannot scale
moxzidhorizontally. One process, one queue per actor, no coordination between servers. More throughput means more independent servers. - You cannot parallelise on-chain builds on one canister. One canister is one job queue; parallelism means deploying more canisters.
- You cannot compile arbitrarily deep machine-generated expressions in a tab. A guest frame on V8's stack costs roughly ten times a wasmtime frame. Hand-written code does not come close; generated code should chunk its expressions or use the CLI.
Next#
- CLI quickstart — the runtime almost everyone starts with.
- Your first actor — the
moxzidpath, end to end, in one page. - Coming from moc — if you already have a moc-based build to port.