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.

issue #42 → pull requestan AI agent pipeline
✓Plan the change09:08 · server-1
✓Write the code09:11 · server-1
✕Run the tests09:14 · server-1 stopped working
✓Run the tests, again09:14 · server-2 took over after 30 seconds
✓Open the pull request09:16 · server-2
◷Wait for a person to review2 days · no server is waiting
✓Merged. Close the issueThursday 11:02 · server-3
Result: one pull request. Nobody had to notice, restart or repair anything.
1
Layer 1 · for everyone

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.

more ideas

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.
built in, not built by you

Every one of these systems gets this for free.

A server restarts in the middle of a step.
Another server runs that step again. What was already saved is not saved twice.
A process waits days for a person or a payment.
The wait is a row in the database. It uses no memory and survives every deploy.
Two things happen to the same order at once.
Each actor handles one message at a time. There is one owner per order, so there is no race.
An outside system is slow or down.
Messages are retried under a policy you set. What keeps failing is kept, so you can read it and send it again.
Nobody knows where a process is stuck.
You can look at every actor and every waiting message, and pause, retry or cancel them.
2
Layer 2 · for architects

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.

six systems, message by message

Follow the messages through a system.

Press play, or click a step. The names are examples: your actors get the names of your business.

built-in actors

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.

from problem to design

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.

  1. The promiseWhat counts as success? What must never happen?
  2. Who and whatWhich facts happen, and what causes them?
  3. Who owns each ruleWhich data must one decision see together?
  4. Identity and lifeWhat is each actor called? Who creates and ends it?
  5. Responsibility cardsWhat does each actor decide, own and leave to others?
  6. ProtocolsWhich messages exist, and what does a reply prove?
  7. Coordination and timeWhat happens on a timeout, a repeat or a cancel?
  8. The outsideWhich calls leave the system, and what if one repeats?
  9. Check and simplifyCan a short trace break a rule? Which actors can go?
3
Layer 3 · for engineers

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.

the turn

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.

1 claim

Claim

A node takes the next due message and a time-limited lease on the actor.

2 run

Run

Your handler reads the state and decides. Everything it wants to change is buffered.

3 commit

Commit

Everything is written together, or not at all.

new state + outgoing messages + new actors + outcome
4 sleep

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.

guarantees

Six guarantees, each tied to tests.

G1

Serial

Turns of one actor never overlap.

G2

Atomic

State, messages and outcome are saved together or not at all.

G3

One outcome

Every accepted message ends exactly once. None is lost, none completes twice.

G4

Effects once

Effects inside the system happen exactly once. A handler runs again only if its turn was not saved.

G5

Order

Messages arrive in order per actor, and never early.

G6

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.

What Cicada does not promise

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.

scale

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.

nodeSQLite
1

One host

One binary and one SQLite file. Enough for a first product or a pilot, with nothing else to install.

nodenodenode
PostgreSQL
2

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.

TypeScriptKotlinRust
serverPG
3

Workers anywhere

Workers lease turns over HTTPS. They need no database credentials, can run in another network, and can be written in another language.

0memory used by an actor that is waiting
16turns at once per node by default; you set the number
30 slease, renewed every 10 s; this is how fast a dead node is noticed
15 minlongest turn by default, adjustable per actor type
  • 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.
languages

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(())
    }
}
The same counter actor. All three can run against one server at the same time.

A flow is a long process written as ordinary code

Each step is saved when it finishes. A saved step never runs again.

flow onboarding.rsRust
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?;
journal onboarding/n1saved progress
✓ create-account   acc-f3f5ac1e
✓ send-welcome
◷ cool-off         due in 60 s
The sleep is a stored message. No process is waiting.
operate

See every actor, mailbox and outcome.

cicada tuithe terminal UI, on a paused actor with three waiting messages
Cicada terminal UI showing the actor sync/acme, its state as JSON and three pending messages in its mailbox
  • 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.
fit

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.
status

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.

Contact
cicada.helico.app