Skip to content
DocspackagesDocumentation

@lunora/platform-celld

Runs a Lunora app on celld, the self-hosted distributed Durable Objects daemon, by recomposing the Cloudflare adapters under celld's capability matrix.

@lunora/platform-celld is experimental. It is a celld implementation of the @lunora/platform host contracts. celld is a self-hosted, distributed Durable Objects daemon: each node embeds V8, executes Wrangler bundles, and coordinates cell ownership through an S3-compatible (or GCS / Azure Blob) bucket instead of a control plane.

Because celld implements the Workers/Durable Object API itself — DurableObjectState key-value storage, state.storage.sql, alarms, the hibernation WebSocket surface, namespaces with idFromName and RPC stubs — this package does not reimplement the adapters. It recomposes @lunora/platform-cloudflare's adapters under celld's honest capability matrix (CELLD_CAPABILITIES in @lunora/platform):

import { createCelldShardPlatform, createCelldWorkerPlatform } from "@lunora/platform-celld";

const platform = createCelldShardPlatform(state); // inside a cell (Durable Object)
const worker = createCelldWorkerPlatform(env); // in the worker entry

Installation

pnpm add @lunora/platform-celld

What celld supports

Ratings track celld v0.6.1. celld v0.6.0 was its first beta. celld v0.3.0 shipped state.storage.sql, so the Lunora shard engine mounts on a cell unchanged, and v0.3.0/v0.4.0 added D1, KV, R2, Queues, Workflows and fleet-wide Cron Triggers as real bindings. v0.4.1–v0.5.1 closed the remaining Lunora blockers: a queue consumer may export fetch() on the same worker (so Queues and ctx.mail work), getTags() exists and hibernatable sockets survive their cell hibernating, and Containers ship (Experimental in celld). v0.6.0 changes no rating; it drops the invalid-UTF-8 refusal on TEXT reads and keeps empty R2 key segments. v0.6.1 changes no rating either: events on one object may now overlap at an await unless blockConcurrencyWhile() closes the input gate (as on Cloudflare), and it adds partial Python Workers support, which Lunora does not use.

native: sharded state, localSql, shard alarms, commit-ordered tables, global tables (D1), KV, object storage (R2), Queues, Workflows, Cron Triggers, WebSocket hibernation, Containers.

emulated: ctx.mail (Resend over Queues, as on Cloudflare), cross-shard fan-out, durable streams, memory tables, server reactors, the scheduler, and the R2-backed backup/CDC-archive paths.

unsupported: shard placement and read replicas. celld makes no placement, migration, or jurisdiction promise — a deliberate non-goal, not a missing binding, so there is no upstream gap to file. A node carries no region, locationHint is not read, and rebalancing moves hibernated cells toward each node's share of CELLD_PLACEMENT_WEIGHT (CPU count by default), never toward a reader. A hint therefore has nothing to act on, and a read replica has no region to be nearer the reader in.

The rest are managed Cloudflare products celld has no binding for: Workers AI (and with it defineAgent, whose loop compiles onto celld's Workflows but has no model to call), Vectorize, Browser Rendering, Images, Analytics Engine, Pipelines, Hyperdrive, Secrets Store, plus the Cache API (an always-miss stub on celld, rated httpCache) and Cloudflare Access. Codegen gates each one that has a ctx.* surface off for target: "celld" in lunora.config.ts, with a platform_unsupported_feature diagnostic naming the feature; the Cache API and Cloudflare Access have no such surface, so codegen does not gate them.

Using it

Set the target once and the CLI drives celld's own tools:

lunora.config.ts
export default { target: "celld" };
  • lunora dev runs codegen watch and the studio, and serves the worker with celld dev — even in a project on @lunora/vite, whose dev server runs the worker in workerd. Start the frontend's dev server separately.
  • lunora deploy runs the usual pipeline (codegen, schema-drift gate, binding reconcile, validation) and ships with celld deploy, which reads the fleet bucket from CELLD_BUCKET plus the standard AWS / GCS / Azure credential environment. --dry-run maps to celld deploy --dry-run (bundle without writing); --preview, --env, --temporary and --outdir are refused: celld has no equivalent.
  • The dev projection is written when lunora dev starts and marks the worker as development (WORKER_ENV, as wrangler dev does); celld dev watches the projection, not wrangler.jsonc, so restart lunora dev after editing the config.
  • Both commands hand celld a projection of wrangler.jsonc, written to .celld.wrangler.json beside it: celld refuses the Cloudflare-only keys Lunora writes (observability, limits, version_metadata, …), and the CLI names each one it leaves out. The projections, celld's .celld/ state and each service's .celld.service.<name>.wrangler.json are added to the app's .gitignore when they are written, since a service's projection carries its .dev.vars values.
  • The celld binary is run from PATH (curl -fsSL https://celld.dev/install.sh | sh), never through npx / bun x; celld deploy also needs esbuild on PATH, and a live deploy needs CELLD_BUCKET. lunora deploy, lunora dev and lunora doctor check these before they write anything, and warn when celld is older than the version the ratings track.
  • lunora logs and lunora env push refuse the target: celld has no log tail and no secret store — see Secrets.
  • A worker entry that is a Vite virtual module (main: "virtual:lunora/worker", the tanstack-start / vinext templates) ships from the Vite build output: run the build, then lunora deploy. The projection reads the config @cloudflare/vite-plugin recorded in .wrangler/deploy/config.json, writes .celld.wrangler.json into the build's output root with main and the assets directory rebased onto it, lets celld re-bundle the chunks (its no_bundle loads the entry module only), and removes the plugin's .assetsignore when it matches nothing — celld refuses the file. celld dev rebuilds from source, which such an entry does not have, so lunora dev refuses it and vite dev serves the worker in workerd with a notice saying so.

Secrets

celld has no secret store. The only way to hand a value to a deployed worker is vars in the Wrangler config, and celld deploy writes those — as plain strings — into the deployment it stores in the fleet bucket. .dev.vars is read by celld dev only; celld deploy never reads it, by design, so a local credential cannot reach a fleet. celld v0.5 removed node-level injection (CELLD_VAR_*, CELLD_VARS_FILE): a node started with either refuses to boot. Lunora's ctx.secrets (Secrets Store) is rated unsupported, and codegen refuses it for target: "celld".

So anyone who can read the fleet bucket can read every vars value in plaintext. Encryption at rest (SSE / KMS) protects against the storage provider's disks, not against a caller holding read credentials. That is no wider than celld's trust boundary already is — the bucket holds every cell's data and the fleet's peer-signing secret, so read access already means the database and the fleet — but it is weaker than Cloudflare, where a secret is write-only once set.

Treat the bucket as the secret

Whatever holds a value, the fleet bucket has to be guarded like the database it is:

  • One fleet per bucket (or per prefix with its own credentials). Nothing else — backups, analytics, other teams' tooling — gets read access.
  • Least-privilege credentials. Nodes and the machine that runs celld deploy need access; nobody else needs any. Use workload identity over long-lived keys where the provider offers it.
  • Encryption at rest (SSE-KMS, CMEK) with access logging on the bucket, so a read is at least recorded.
  • Clean up old deployments. Every celld deploy leaves its version — and its vars — under deploy/<name>/. After rotating a value, delete the versions that still carry the old one.
  • Encrypt node-to-node traffic. Peer traffic is plaintext HTTP; run the fleet on a private network or an encrypted overlay (WireGuard, Tailscale), and terminate public TLS at the ingress proxy.

Keep real secrets in a secret manager

For anything more sensitive than the data itself — payment provider keys, credentials to other systems — or when a value must be write-only, audited, or separately revocable, keep it out of the bucket entirely: store it in a secret manager (Vault, AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical, …) and fetch it from the worker at runtime. Only one bootstrap credential then lives in vars:

  • scope it to read exactly the secrets this app needs, nothing else;
  • make it short-lived or cheap to rotate (a Vault AppRole secret ID, a scoped service token), so a leak through the bucket is revoked at the manager without redeploying anything else;
  • cache what it fetches in memory per isolate with a short TTL, rather than calling the manager on every request.

A celld node gives a worker no identity of its own, so this moves the problem to one small, auditable, revocable credential rather than eliminating it.

What vars is still fine for

Non-secret configuration (feature switches, public URLs, region names), and values whose exposure is bounded by what the bucket already exposes. Put them in wrangler.jsonc vars — the projection keeps them — and keep local-only values in .dev.vars for celld dev.

Upgrading celld

Moving a fleet from v0.5.1 to v0.6.0 cannot be a rolling update when it runs with fleet durability: stop every v0.5.1 node, then start the v0.6.0 nodes. A v0.6.0 node recovers its previous log session only from a follower that returns the ranged tail format, which a v0.5.1 follower does not, so a v0.6.0 node started beside v0.5.1 followers refuses to start. A fleet with bucket durability has no followers and can roll node by node. v0.6.0 → v0.6.1 rolls node by node; set CELLD_LTX_RETENTION_SECS or raise CELLD_MAX_ASSET_FILE_BYTES above 25 MiB only once every node runs v0.6.1. Check the upgrade notes in celld's docs/README.md before any other version bump: v0.4.0 → v0.4.1 rolls, but once the last v0.4.0 node stops, a v0.4.0 binary must not be started again.

API

createCelldShardPlatform(state)

Type: (state: unknown) => Omit<ShardPlatform, "secretValues">

Builds the shard-side platform inside a cell (the Durable Object). state is the cell's DurableObjectState. The result carries no secretValues, because celld has no secret store (see Secrets).

createCelldWorkerPlatform(env, options?)

Type: (env: unknown, options?: WorkerPlatformOptions) => WorkerPlatform

Builds the worker-side platform in the worker entry from its env bindings, with the same WorkerPlatformOptions as @lunora/platform-cloudflare.

Conformance

pnpm run test:celld boots celld dev on a TCK worker and runs every leg of the @lunora/platform and @lunora/shard-engine contract suites inside a real cell (the celld vitest project, gated by LUNORA_CELLD_TESTS=1; CI runs it against a pinned, checksum-verified release). Against v0.6.1 the celld project passes 75 tests and skips 8, each for a test hook or surface the host does not supply, as on the Cloudflare workerd run (among them recycle simulation, a terminal dispose, dispatch-level isolation, runtime cron registration, and the dead-letter legs below). The SchedulerHost legs run against SchedulerDO through createSchedulerHost, one scheduler cell per leg; the job's delivery is recorded rather than sent to LUNORA_ORIGIN_URL, so the at-least-once leg checks that the cell's alarm fires and drains the job. The two dead-letter legs still skip: the host has no hook to force a job into the dead-letter set.

The same run drives the binding-backed ratings through Lunora's own adapters, in the call shapes the runtime uses: D1 via D1Client (sessions and bookmarks, batch, UPDATE … RETURNING, fts5), KV via createKv (JSON, metadata, TTL, prefix listing), R2 via createStorage plus the raw sha256 / startAfter / delimiter calls the CDC archive and backups make, a queue consumed by dispatchQueueBatch on the same worker that exports fetch (a throwing first delivery comes back with attempts: 2), a workflow through step.do and waitForEvent, one cron tick, Discord channel verification through verifyDiscord (Ed25519, which celld gained in v0.6.0), sqliteVectorStore({ ann })'s vec0 index inside a cell (the worker sets sqlite_vec), jsCodeTool through a worker_loaders binding (a script's value and logs come back, fetch is refused under globalOutbound: null, and the CPU budget stops a busy loop), and the dynamic shard registry through createDynamicShardRegistry on a ShardRegistryDO cell (register, idempotent re-register, unregister, and a second client listing what the first wrote). A separate project (__tests__/celld/services/) boots a service into the local state first, as lunora dev does, then starts the app on that state and calls a fetch service and a WorkerEntrypoint RPC service through createServices, the module ctx.services is built from. With LUNORA_CELLD_CONTAINERS=1 and a container engine, it also runs a LunoraContainer declared the way codegen emits one, and routes a request through it to the container's port (celld finds the engine via DOCKER_HOST or the default Docker / OrbStack / Podman socket; colima's needs DOCKER_HOST=unix://$HOME/.colima/default/docker.sock). Three gaps surfaced. A defineQueue({ mode: "pull" }) queue is refused by celld at deploy. The other two would only fail once running — a defineStep({ rollback }) step, and a container with an egress policy (allowedHosts / deniedHosts / interceptHttps) — so they are rated on their own keys (workflowRollback, containerEgressPolicy) and codegen refuses them for target: "celld" with a platform_unsupported_feature diagnostic, which blocks lunora deploy.

With LUNORA_CELLD_S3_ENDPOINT pointing at an S3-compatible endpoint (moto's server in CI), the same project also deploys the TCK worker to a bucket and runs two production nodes against it: a write through one node is served when read through the other, when the owning node is killed mid-lease the survivor takes the cell over from the bucket with the write intact, and a node that joins takes idle cells from the other on its own and serves every value (run with a short CELLD_IDLE_EVICT_S / CELLD_REBALANCE_INTERVAL_MS, since only hibernated cells move).

One difference from workerd surfaced: celld does not deliver a frame sent on an acceptWebSocket socket to a peer inside the same cell. Real clients get every frame, which a separate leg drives over the network (host sends, the wake-time socket id, tag fan-out); the engine harness records frames at the send boundary instead of reading them off an in-cell peer.

Ratings derive from celld's documented compatibility surface (docs/cloudflare-compat.md, docs/services/*.md, docs/limitations.md in the celld repo, at the v0.6.1 tag), confirmed where the TCK reaches.

Scope

Published on the alpha dist-tag and gated by the API-snapshot guard at the experimental tier, alongside @lunora/platform-node: the snapshot records how the surface moves and carries no SemVer promise.