Temporalalpha

Run Motoko actors as Temporal entity workflows, with each turn a local activity and state in Postgres.

Each actor key is a long-running Temporal workflow. Each message runs as a local activity, and Temporal's durable timers drive Motoko timers. The actor's state is stored in Postgres, so the workflow history stays small.

You also need the moxzi SDK and hosts bundles; see Actor platforms.

Prerequisites#

Go 1.22 or later
The Temporal CLI (run.sh starts a development server)
Docker, for Postgres

Create and run a project#

moxzi host new temporal hello

cd hello
ONCE=1 ./run.sh

actor.mo -> actor.wasm + actor.did (245563 bytes, 1 file(s), 50 steps, 0.62s)
Counter/1.inc() -> [1]

Run it a second time. The host is a new process, and the actor's state comes back from the platform's store:

ONCE=1 ./run.sh

actor.mo -> actor.wasm + actor.did (245563 bytes, 1 file(s), 50 steps, 0.60s)
Counter/1.inc() -> [2]

ONCE=1 exits after the demo. Without it, the host keeps running on port 8090 (set PORT to change it), and you can call any key:

curl -X POST localhost:8090/actors/Counter/2/method/inc \
  -H 'content-type: application/json' -d '[]'

--example ledger and --example saga work on Temporal too; see Examples.

The project#

Path	Contents
`actor.mo`	The `Counter` actor type. Each key `Counter/ID` is a separate actor
`host/`	moxzi's Temporal adapter. It's yours to change
`run.sh`	Builds the actor and the host, starts what Temporal needs, and runs the demo

Change actor.mo and run ./run.sh again. New keys use the new code. Existing keys keep their code until they're upgraded; host/README.md describes upgrades.

How it maps#

	Handled by
One message at a time per key	The entity workflow
Actor state	Postgres, in a Docker container named `moxzi-hello-pg` on port 55432 that `run.sh` starts and leaves running. Set `DATABASE_URL` to use your own database, or `PG_PORT` to use another port
Durable timers	`workflow.NewTimer`. After a replay, a timer fires at its original time

Remove the database container with docker rm -f moxzi-hello-pg when you're done.

Configuration#

Variable	Default	Effect
`PORT`	`8090`	The host's HTTP port
`MOXZI_HOST_TOKEN`	random	Token for the host's control endpoints (`/_moxzi/*`)
`DATABASE_URL`	a local container	Postgres connection string
`PG_PORT`	`55432`	Port for the local Postgres container. All projects use the same default, so only one can run at a time