Docs / Actor platforms / How actor platforms work

How actor platforms workalpha

What the platform does, what moxzi does, and how to use the moxzi runtime library from your own host.

On every platform, the Motoko actor runs inside the platform's own process through libmoxzi_rts, a library. moxzi never writes to disk; the platform stores everything.

Who does what#

The platform	moxzi
One actor per key, such as `Counter/1`	Runs the actor's code
Which machine runs which actor	Rolls back a message that traps
One message at a time per actor	Holds an `await` until the reply comes, even across restarts
Delivering calls between actors	Tracks which timers are due
Storing the actor's state	Upgrades: finishes pending work, then migrates state
Durable timers	Remembers which retried calls already ran

A turn#

Each message is a turn. The platform passes the turn to the library together with the version of the actor's state it has stored. The library runs the message and returns the reply and a delta: the pages of memory that changed, plus a small metadata record. The platform saves the delta only if its stored state is still the version the delta was built on. If it can't save, it drops the actor from memory, and the next turn reloads it from storage.

So the platform's store is always the truth, and a crash at any point loses at most the turn in progress, which the caller retries.

Cost#

	Measured
Memory per active actor	About 110 KiB
Actors in one process	100,000 in about 14 GB
Loading an actor from storage	About 0.4 ms
An update compared with the platform's own native actor	1.4× to 4.4× slower, depending on the platform

Using the library directly#

The SDK bundle includes the library, its C header and an example:

File	Contents
`lib/libmoxzi_rts.dylib` (macOS) or `lib/libmoxzi_rts.so` (Linux)	The runtime
`include/moxzi_rts.h`	The C interface
`examples/rts_hello.c`	A minimal host
`adapters/`	The adapter sources `moxzi host new` copies into projects

int  moxzi_rts_new(ns, ns_len, dep, dep_len, &rts);
int  moxzi_rts_add_type(rts, name, name_len, wasm, wasm_len);
int  moxzi_rts_call(rts, method, method_len, url, url_len, body, body_len, &status, &out, &out_len);
void moxzi_rts_free_buf(out, out_len);

moxzi_rts_call takes an HTTP-style request (method, path, JSON body) and returns the response, so a host built on it looks the same as one that talks to a separate service.

cc examples/rts_hello.c -I include -L lib -lmoxzi_rts -Wl,-rpath,lib -o rts_hello
./moxzi build hello.mo -o hello.wasm
./rts_hello hello.wasm

For a statically linked library, download moxzi-rts-static-VERSION-TARGET.tar.xz. It's large, and published in parts: join them with cat moxzi-rts-static-*.tar.xz.part-* > moxzi-rts-static.tar.xz, then check the result against SHA256SUMS.

The adapters for Orleans, Pekko and Ray load the library from MOXZI_RTS_LIB_DIR (Orleans, Pekko) or MOXZI_RTS_LIB (Ray). The Go adapters (Dapr, Proto.Actor, Temporal) link it with cgo when run.sh builds them.

Limitations#

Limitation
Certified data	Not available on any actor platform