Durable actor framework
Pipelines, workflows and AI agents that never lose their place.
Cicada is a framework for building systems from small durable workers, called actors. Each one remembers its state and survives crashes and deploys. Put them together and you get CI/CD, agent pipelines, schedulers and alerting, on nothing more than a database.
What you can build
Anything where work takes time, has several steps, or must not be lost. Here are six systems, worked out down to the last message. Pick one to see its actors.
AI agent pipeline
An issue goes in, a reviewed pull request comes out. With pause, resume and a person in charge. Our own code factory works this way.
Git hosting with CI/CD
Repositories, merge requests, pipelines, runners and deploys. A small GitLab, built from five kinds of actor.
Order workflow
Reserve stock, take payment, ship. Give the stock back when the payment never arrives.
Scheduled jobs
Nightly jobs that retry, report to the team, and raise an alarm when they did not run at all.
Alerts and on-call
Notice that something went quiet, open one incident, and escalate until a person responds.
Notification hub
One event reaches the right people: in Slack right away, or in one daily mail for those who prefer that.
The same parts build many other systems.
- Customer onboarding
- Collect documents, check them, wait for approval, remind after three days.
- Subscription billing
- Renew on time, retry a failed payment, give a grace period, then suspend.
- Bookings
- One actor per room or seat. A hold expires by timer. Double booking cannot happen.
- Integration hub
- Sync two systems page by page, within their rate limits, and keep what failed.
- Research agents
- A planner splits a question, agents answer the parts in parallel, a person approves the result.
- Staged rollouts
- Release to 1%, wait, check health, go to 10%. Roll back when an alarm fires.
- Device fleets
- One actor per device: its last known state, its waiting commands and a silence alarm.
- Document sign-off
- Ask five people, wait for all of them or for the first refusal, chase the slow ones.
- Mail campaigns
- A timeline per contact: mail, wait a week, check, next mail. Unsubscribing cancels the rest.
- Live chat
- Sessions that keep unconfirmed messages and replay them in order after a reconnect.
Every one of these systems gets this for free.
How the actors work
Each system above is a handful of actors that send each other messages. This layer shows who they are and what moves between them.
An actor owns one thing
It has a name, such as order/1042, and its own saved state. Nobody else changes that state.
Actors talk by message
A message waits in the mailbox of the actor it is for. Each actor handles one message at a time, in order.
A decision is saved in one step
The new state and the messages it sends are written together. A timer is just a message to yourself, for later.
Follow the messages through a system.
Press play, or click a step. The names are examples: your actors get the names of your business.
Ten actors come ready-made.
You do not write a scheduler or a rate limiter. They ship with Cicada, they are ordinary actors, and they carry the same guarantees as your own. Pick one to see how it works.
Design your system together with an agent.
Cicada ships with a design skill for coding agents. You tell it one or two stories from your business, including how they go wrong. It asks at most three questions at a time and writes the design into your repository, with diagrams: which actors exist, what each one owns, which messages they send and what happens on a timeout.
The same skill reviews a system that already exists. It draws the actors and messages from the code and reports the weak spots, each with a trace of how it fails.
- The promiseWhat counts as success? What must never happen?
- Who and whatWhich facts happen, and what causes them?
- Who owns each ruleWhich data must one decision see together?
- Identity and lifeWhat is each actor called? Who creates and ends it?
- Responsibility cardsWhat does each actor decide, own and leave to others?
- ProtocolsWhich messages exist, and what does a reply prove?
- Coordination and timeWhat happens on a timeout, a repeat or a cancel?
- The outsideWhich calls leave the system, and what if one repeats?
- Check and simplifyCan a short trace break a rule? Which actors can go?
Under the hood
What happens when one actor handles one message, what Cicada guarantees, how it scales, and what the code looks like in three languages.
One message, one transaction.
An actor is a row of state plus a mailbox in your database. Handling one message is called a turn. Every turn has the same four steps.
Claim
A node takes the next due message and a time-limited lease on the actor.
Run
Your handler reads the state and decides. Everything it wants to change is buffered.
Commit
Everything is written together, or not at all.
Sleep
The actor leaves memory. It is a row again until its next message is due.
Why “Cicada”? A cicada waits underground for years and comes up right on time. A Cicada actor waits in the database and wakes when its next message is due.
Six guarantees, each tied to tests.
Serial
Turns of one actor never overlap.
Atomic
State, messages and outcome are saved together or not at all.
One outcome
Every accepted message ends exactly once. None is lost, none completes twice.
Effects once
Effects inside the system happen exactly once. A handler runs again only if its turn was not saved.
Order
Messages arrive in order per actor, and never early.
No hidden retry
Cicada never re-runs a handler that returned. Retries follow the policy of the message.
Each guarantee is listed next to the tests that prove it. The same conformance suite runs on every store: in memory, SQLite and PostgreSQL. A randomised simulation injects faults such as crashes, lost replies and expired leases, and checks the guarantees on the history that results.
Calls to outside systems, such as a payment or an email, can happen more than once after a crash. Every message has a fixed id to use as idempotency key, so the outside system can refuse the repeat.
Start with one file. Grow without a redesign.
The same actor code runs in all three setups. You change how it is deployed, not how it is written.
One host
One binary and one SQLite file. Enough for a first product or a pilot, with nothing else to install.
Many nodes
Point more nodes at the same PostgreSQL database. Nodes are equal: there is no leader, no broker and no cluster protocol. Others pick up the work of a node that dies.
Workers anywhere
Workers lease turns over HTTPS. They need no database credentials, can run in another network, and can be written in another language.
- Scale one kind of work on its own: start extra workers for one actor type only.
- Pin an actor to one node or worker when it must run on a specific machine.
- Deploy without losing work: a node stops claiming, finishes its turns, then closes.
- Each handled message is one database commit. Cicada puts simplicity and correctness before raw speed.
One actor system, three languages.
- Rust
- The core: server, stores, command line and terminal UI. Embed it in your service or run it as a binary.
- TypeScript
- A worker for Node.js. Actor types are defined with Zod schemas.
- Kotlin
- A worker for the JVM, on coroutines. In preview.
Every actor type publishes a contract: the JSON Schemas of its state and messages, plus a hash. The server keeps one contract per type and refuses a worker whose contract differs. Each worker library has the same version number as the Cicada release it was tested against, together with a Rust server and a Rust worker.
#[derive(Serialize, Deserialize, JsonSchema)] #[serde(tag = "type")] pub enum CounterMsg { Add { amount: i64 }, } impl Actor for CounterActor { type Ref = Counter; type State = CounterState; async fn handle(&self, turn: &mut Turn<Self>, message: CounterMsg) -> HandlerResult { match message { CounterMsg::Add { amount } => turn.state_mut().total += amount, } Ok(()) } }
const Counter = actorType({ type: "counter", state: z.object({ total: z.int() }), messages: { Add: z.object({ amount: z.int() }), }, handle(turn, message) { switch (message.type) { case "Add": turn.state = { total: turn.state.total + message.amount }; return; } }, }); const source = new HttpTurnSource("https://actors.internal"); await new Worker(source, [Counter]).start();
@Serializable sealed interface CounterMsg { @Serializable @SerialName("Add") data class Add(val amount: Long) : CounterMsg } @Serializable @SerialName("CounterState") data class CounterState(val total: Long = 0) val Counter = actorType<CounterState, CounterMsg>("counter") { handle { msg -> when (msg) { is CounterMsg.Add -> state = state.copy(total = state.total + msg.amount) } } }
A flow is a long process written as ordinary code
Each step is saved when it finishes. A saved step never runs again.
let account_id: String = step.run("create-account", |key| async move { Ok(services.create_account(email, &key).await?) }).await?; step.run("send-welcome", |key| async move { Ok(services.send_welcome(email, &key).await?) }).await?; step.sleep("cool-off", Duration::from_secs(60)).await?;
✓ create-account acc-f3f5ac1e ✓ send-welcome ◷ cool-off due in 60 s
See every actor, mailbox and outcome.
- Terminal UI and command line: inspect, pause, resume, retry, cancel, deliver now, purge.
- HTTP API with a generated OpenAPI schema. You add your own authentication.
- Traces and metrics through OpenTelemetry.
- A live stream of state changes, to build dashboards on.
- A readiness probe and an ordered shutdown, made for container platforms.
- Skills for coding agents with each release: one to write Cicada code, one to design or review an actor system.
When to use it, and when not.
A good fit
- Processes that take minutes, days or months.
- Work that must not be lost or done twice.
- Rules that need one clear owner per customer, order or device.
- Teams that prefer a PostgreSQL database over a new platform to run.
Not the right tool
- High-volume event streaming.
- Request paths that cannot afford a database commit.
- Heavy data processing or analytics.
- A problem that one function or one table already solves.
Cicada is not public yet.
The framework is in active development at Helico and is not released as a public library. Do you have a pipeline, a workflow or an agent that must not lose work? Tell us about it, and we will sketch the actors with you.