moxzid flag referencealpha
What are the command-line flags of the moxzid server?
Every flag of the moxzid binary, transcribed from its own --help. If this page and moxzid --help disagree, the binary is right and this page is a bug. For the endpoints it serves rather than the flags it takes, see the HTTP API.
moxzid runs Motoko actors off-chain with Internet Computer semantics. It takes no subcommands — one process, one manifest, one listen address.
Where things live#
| Flag | Default | Meaning |
|---|---|---|
-m, --manifest <FILE> | actors.json | Manifest declaring the actors to host. |
-l, --listen <ADDR> | 127.0.0.1:7000 | Address to listen on. |
-s, --state <DIR> | (none) | Directory for durable state. |
Without --state the server is in memory and everything is lost when it stops. That is the right default for a scratch run and the wrong one for anything real, so it is explicit either way rather than guessed.
Durability#
| Flag | Default | Meaning |
|---|---|---|
--snapshot-below <BYTES> | (see note) | Snapshot after every message for actors at or below this heap size; above it, rely on the write-ahead log. |
Setting --snapshot-below 0 snapshots never and exercises pure log replay. That is how the recovery path gets tested rather than assumed, and it is what the crash gate runs.
Resource limits#
| Flag | Default | Meaning |
|---|---|---|
--instruction-limit <N> | 40000000000 | Kill any message exceeding this many wasm instructions. |
--cycles <N> | 100000000000000 | Starting compute allowance per actor, in cycles. 0 disables metering entirely. |
The instruction limit defaults to the Internet Computer's own per-message cap of 40 billion. A hosted actor is code someone else wrote; without a cap, an infinite loop in one is an infinite loop in the server. Exhaustion traps, the message is rolled back, and the actor keeps serving.
Cycle metering is on by default on purpose: an allowance nobody develops against is an allowance nobody respects, and the first agent to assume compute is free is the one that starves every other actor on the host.
Scheduled work#
| Flag | Default | Meaning |
|---|---|---|
--heartbeat-ms <MS> | 1000 | How often to run each actor's system func heartbeat. 0 to never. |
--timer-ms <MS> | 100 | How often to check for expired global timers. 0 to never. |
These are separate mechanisms and the second is deliberately faster. A heartbeat runs every round whether or not anything asked for it; a timer runs because a canister set a deadline. Tying timers to the heartbeat would mean --heartbeat-ms 0 silently disabled every Timer.setTimer in every actor.
A heartbeat is a real message: it is charged, it is rolled back if it traps, and it can call other actors.
Network#
| Flag | Default | Meaning |
|---|---|---|
--no-outcalls | off | Refuse http_request outright: hosted actors cannot reach the network. |
--outcall-timeout-secs <SECS> | 30 | How long an outcall may take before it is abandoned. |
--no-outcalls is a switch rather than a deployment detail because a host running code it did not write is exactly where "can this thing phone out?" needs a one-word answer.
Authentication#
| Flag | Meaning |
|---|---|
--auth-token <TOKEN> | Bearer token required on every endpoint except /health and /version. Also read from MOXZID_TOKEN. |
--insecure | Allow binding a non-loopback address without a token. |
The token is a single shared secret, checked in constant time. This is honest alpha-grade authentication: enough to stop a stranger who can reach the port from installing wasm, and no more. TLS belongs in a reverse proxy; roles and per-user keys are post-alpha.
Without --insecure, binding a non-loopback address with no token is refused at startup. POST /install runs arbitrary wasm, so an open port must be a decision someone spelled out rather than a default someone forgot.
Serving the web#
| Flag | Meaning |
|---|---|
--web <ACTOR> | Serve this actor's http_request interface at the root. |
--project <DIR> | Project directory for GET /mops/closure/<entry>. |
With --web, any path that is not a moxzid endpoint becomes a gateway request to that actor, so absolute links in its pages work and the actor is, to a browser, simply a website. The inspector moves to /inspector. Every actor stays reachable at /site/<actor>/<path> regardless.
--project resolves a Motoko file's full dependency closure — mops packages included, transitively — and serves it as JSON, so a browser forge can stage exactly what moxzi build would compile. It uses the same resolver and the same /src and /pkg VFS mapping as the CLI, byte-identity included.
Observability#
| Flag | Default | Meaning |
|---|---|---|
--history <N> | 50 | Keep this many recent messages per actor. 0 disables recording. |
--log-json | off | One JSON line per event on stderr instead of prose. |
-v, --verbose | off | Forward each actor's debug output. |
History records method, caller, a bounded argument preview and the outcome. It is served as JSON at GET /history/<actor> and is what the inspector displays. --log-json covers messages handled, installs, upgrades, recoveries and shutdown; the default stays human.
Next#
- The HTTP API — the endpoints, rather than the flags.
- Operating moxzid — running this as a service.
- Authentication — what must never be exposed.