Skip to main content

Crate serve_celld

Crate serve_celld 

Source
Expand description

§serve-celld (experimental)

Run a serve app durably on celld, self-hosted distributed Durable Objects, part of the Everruns ecosystem.

Experimental. Like serve, this is a proof of concept with no compatibility promise.

On celld a Durable Object (a cell) has one owner node at a time and a replicated SQLite database that survives a move to another node. A container the cell supervises does not: a move, a node restart or a reset destroys it. So the agent runs in the container and the cell keeps what must survive:

  • the latest snapshot of serve’s state (the session catalog, the engine’s canonical event log and the workspace), taken whenever the app is idle;
  • a journal of the requests that arrived since, replayed into a fresh container after the snapshot is restored.

This crate is the container half. It serves serve’s own /v1 wire API and three routes only the cell calls:

  • GET /celld/state: {"boot_id", "booted", "busy"}. A new boot_id tells the cell the container is fresh and must be restored. Never boots the app.
  • GET /celld/snapshot: a tar of the data directory, with every SQLite database copied through the online backup API so the copy is consistent. 409 while a turn runs.
  • PUT /celld/restore: unpack a snapshot into the data directory. 409 once the app has booted, so a restore can never race live state.

serve boots on the first other request, after the cell had its chance to restore. The JavaScript cell example decides when to snapshot, what to journal and when to replay.

use serve::prelude::*;

#[agent]
fn assistant() -> Agent {
    Agent::builder()
        .model("anthropic/claude-sonnet-5")
        .instructions("Be brief.")
        .build()
}

#[tokio::main]
async fn main() -> serve::Result {
    // No command (what the container runs) or `celld`: the celld contract
    // on :8080. `dev`, `start`, `eval`, `manifest`, `deploy`: serve's own.
    serve_celld::start(App::builder().discover().build()).await
}

Structs§

Options
How router boots the app.

Constants§

MAX_SNAPSHOT_BYTES
The largest snapshot PUT /celld/restore accepts.
PORT
The port the container listens on, and the cell’s defaultPort.

Functions§

default_data_dir
SERVE_DATA_DIR when set, else serve-celld in the temp directory.
restore_dir
Replace dir with the snapshot in bytes. Accepts only regular files and directories with relative paths that stay inside dir; anything else fails the whole restore before dir is touched. Returns the file count.
router
The celld container contract around app: /celld/* and serve’s /v1 wire API.
snapshot_dir
Tar dir. SQLite databases go through the online backup API, which reads a consistent copy while serve keeps them open; their -wal, -shm and -journal siblings and lock files are left out, since the copy already holds every committed page. Other regular files are copied as they are; symbolic links and special files are skipped.
start
Run the app: with no command, or with celld, serve the celld container contract; any other command is serve’s (see serve::start).