Skip to content
Cello
Esc
↑↓navigate↵open⌘Jpreview
On this page

Configuration reference

Every CELLO_* environment variable, its default, and what it changes. Boolean variables accept only 0 or 1.

You configure a node and every operator subcommand through the environment. An unset variable selects its default. A Boolean variable accepts only 0 or 1. Cello exits at startup on an invalid value, including a removed setting listed at the end.

Telemetry variables (CELLO_OTEL*, OTEL_*) live on the telemetry page.

Storage

Variable Default Effect
CELLO_BUCKET unset (required) The fleet bucket, with an optional key prefix. Same as --bucket. See storage.
S3_ENDPOINT unset The S3-compatible endpoint. Same as --endpoint.
AWS_REGION, AWS_DEFAULT_REGION us-east-1 The storage region.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN unset Explicit AWS credentials. The standard AWS credential chain is also available.
CELLO_DEPLOY_AWS_ACCESS_KEY_ID, CELLO_DEPLOY_AWS_SECRET_ACCESS_KEY, CELLO_DEPLOY_AWS_SESSION_TOKEN unset A second, read-only credential over the deployment pointer and bundles: a node reads deploy/ and deploy-blobs/ with it and everything else with AWS_*. S3 only; the access key and secret are both required.
GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_SERVICE_ACCOUNT_KEY unset Google credentials for a gs:// bucket. Application Default Credentials are also available.
AZURE_STORAGE_ACCOUNT_NAME unset The storage account for an az:// bucket.
AZURE_STORAGE_ACCOUNT_KEY unset The storage account key. Do not combine it with an identity selector.
AZURE_AUTHORITY_HOST, AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE unset The AKS workload identity environment. The authority must be the public Azure host.
AZURE_STORAGE_USE_EMULATOR unset Set to true to develop against Azurite.

Listeners and identity

Variable Default Effect
CELLO_ADDR 127.0.0.1:8080 The public Worker listener. Same as --listen.
CELLO_INTERNAL_ADDR 127.0.0.1:0 The peer and operator listener. Same as --internal-listen.
CELLO_ADVERTISE unset The internal address that peers can reach. Same as --advertise.
CELLO_UNSAFE_PUBLIC_ADVERTISE 0 Set to 1 to permit a literal public IP in CELLO_ADVERTISE. It does not resolve a DNS name or restrict the internal listener.
CELLO_OPERATOR_TOKEN unset A bearer token the whole fleet shares. When set, every internal-listener route requires Authorization: Bearer <token> and answers 401 without it. Set but empty: the node refuses to start.
CELLO_TRUST_FORWARDED_HEADERS 0 Set to 1 to trust X-Forwarded-Host and X-Forwarded-Proto. Same as --trust-forwarded-headers.
CELLO_NODE generated, pinned to node-id in the data dir An explicit node-session ID: 1 to 128 ASCII letters, numbers, dots, dashes, or underscores, but not . or ...
CELLO_WATCH platform temp dir The local work directory for SQLite and replication. Set it to a persistent directory to keep the node ID across restarts.
CELLO_ESBUILD esbuild on PATH The path of the esbuild executable: the self-contained release binary, since on Linux it runs with reads confined to the project and its read roots.
CELLO_DEV_STATE PROJECT/.cello/dev The cello dev state directory. Same as --state.
RUST_LOG info The runtime log filter.

Deployments

Variable Default Effect
CELLO_DEPLOY_POLL_S 30 The deployment pointer poll interval in seconds.
CELLO_DEPLOY_MAX_AGE_S 60 Seconds before Cello forces a resident Durable Object onto a new deployment. 0 forces at once.

Requests and isolates

Variable Default Effect
CELLO_OPERATION_DEADLINE_MS 15000 The deadline for a non-restore operation.
CELLO_MAX_CELL_REQUESTS 64 Concurrent fetch events for one Durable Object. Past it, Cello answers 503 with Retry-After: 1.
CELLO_MAX_CELLS_PER_ISOLATE 32 Cells packed into one isolate. Lower it for heavyweight cells such as agents.
CELLO_MAX_REQUEST_BODY_BYTES 1 GiB The body limit for a public Worker request or a direct Durable Object request.
CELLO_TMP_MAX_BYTES 67108864 (64 MiB) The per-request /tmp size limit in bytes. A write past it fails with ENOSPC.
CELLO_HANDLER_BUDGET_S 300 The JavaScript handler budget in seconds.
CELLO_BACKGROUND_BUDGET_S 30 Post-response background budget in seconds. Past it the driver ends leftover timers and waitUntil work. A streaming response body is not background work and is never charged to it: it runs while the client stays connected and the body keeps producing. While a body streams, expiry ends the waitUntil claim, but timers that work already started keep running until one budget window after the body ends.
CELLO_FETCH_TIMEOUT_S 120 Outbound fetch timeout in seconds.
CELLO_SQL_STATEMENT_MS unset (unbounded) The per-statement SQL time bound in milliseconds. A timed-out statement fails with a catchable timeout error and rolls back.
CELLO_V8_HEAP_LIMIT_MB unset Per-isolate V8 heap limit in MiB.
CELLO_CACHE_SCOPE script Which cache entries a Worker sees: script isolates each script’s entries, deployment shares one caches.default and one set of caches.open(name) namespaces across every script of the serving deployment. See security.
CELLO_EGRESS open public refuses Worker dials to non-public addresses. See security.
CELLO_EGRESS_ALLOW unset Exceptions as comma-separated CIDRs or host:port pairs.

Placement and memory

Variable Default Effect
CELLO_ACTIVATIONS 8 per CPU, at least 16, at most 128 Concurrent cold-cell activations.
CELLO_MAX_RESIDENT_CELLS unset The hard limit for resident cells, enforced at admission.
CELLO_IDLE_EVICT_S unset Seconds after which an idle cell leaves memory and hibernates. Unset: only pressure or the residency cap removes an idle cell.
CELLO_PLACEMENT_WEIGHT the CPU count The ownership share of this node, relative to the other nodes.
CELLO_REBALANCE_INTERVAL_MS 5000 The fleet sample interval and maximum age. 0 disables balancing.
CELLO_MAX_RSS_MB 80% of the available memory The memory threshold for pressure shedding, on the greater of the allocator-adjusted RSS and the active cgroup working set. 0 disables the threshold and the absolute cap.
CELLO_MEMORY_SCOPE container Which cgroup the pressure sample and limit read: container measures the cgroupfs root, self the process’s own cgroup v2 leaf. With self and an unset CELLO_MAX_RSS_MB, the threshold defaults to 80% of the leaf’s memory.max.
CELLO_C_TRIM_MB 8 Freed C-heap growth, in MiB, that earns another malloc_trim on the sampler tick.
CELLO_SQLITE_CACHE_KB 2000 The SQLite page-cache budget per resident cell connection, in KiB.
CELLO_ASSET_CACHE_DIR unset Downloaded static-asset cache directory.
CELLO_ASSET_CACHE_BYTES compiled-in default Asset cache limit in bytes.
CELLO_LOCAL_CACHE_MAX_BYTES 2 GiB Hibernated SQLite cache limit. 0 disables it.
CELLO_PRESSURE_OWNERSHIP release release hands a pressure-evicted cell to a peer; sticky keeps the ownership record so the cell wakes locally.
CELLO_ALARM_RESIDENT_MS 3600000 Near-alarm residency window in milliseconds.
CELLO_WAKER_TICK_MS 60000 Orphan-alarm scan interval in milliseconds.
CELLO_TOKIO_THREADS the CPU count Host Tokio worker threads.

Durability

Variable Default Effect
CELLO_DURABILITY fleet fleet: each write waits for one or two peer nodes to hold it on disk (a single node waits for the bucket instead). bucket: always wait for the bucket.
CELLO_BUCKET_BUNDLES 0 In bucket posture, 1 groups each flush round’s dirty rows into shared bundle proofs. Any other value stops startup.
CELLO_BUCKET_BUNDLE_LINGER_MS 0 Hold a bundle round open this many milliseconds after the first dirty wake so concurrent writes share one PUT. Values above 1000 clamp to 1000.
CELLO_LOG_PIPELINE 4 Fleet log rounds in flight.
CELLO_LOG_HEDGE_MS adaptive (4x the slowest recent append, at least 250 ms) The wait before a second copy of a slow log append. 0 disables the copy.
CELLO_LTX_TRUNCATE_PAGES 128 (512 KiB) The WAL size, in pages, at which Cello truncates the WAL at the next checkpoint. A database larger than 4 MiB waits until the WAL is larger than the database. 0 disables it.
CELLO_LTX_RETENTION_SECS unset (no deletion) A positive value enables epoch GC: the owner deletes prefixes below the restore base, keeping its own epoch, the one before it, and each epoch younger than this many seconds.
CELLO_LTX_COMPACTION 1 Creates additive L1 objects so a takeover reads tens of objects instead of thousands. Set 0 on every node of a mixed fleet until all nodes read v0.5.2 block objects.
CELLO_LTX_COMPACTION_MIN_TXIDS 256 The TXID distance that queues an L1 compaction.
CELLO_LTX_COMPACTION_MIN_MB 32 (at most 64) The L0 MiB that queue an L1 compaction.
CELLO_LTX_COMPACTIONS 2 Concurrent L1 compactions per node.
CELLO_LTX_PAGED 1 1: a takeover of a chain of at least CELLO_LTX_PAGED_MIN_MB reads pages from the bucket on first use. Set 0 to download every chain, and on every node of a mixed fleet with a node before v0.4.1.
CELLO_LTX_PAGED_MIN_MB 256 The chain size, in MiB, from which a restore pages. 0 pages every chain.
CELLO_LTX_HYDRATE_MBPS 16 The background fill rate of a paged cell, in MiB per second. 0 keeps the cell sparse.
CELLO_LTX_DURABILITY_TIMEOUT_SECS 10 The budget for one durability proof, and for the final snapshot of a handoff. A queued write waits at most six budgets.
CELLO_TTL_MS 10000 Node lease lifetime in milliseconds; the lease renews at one third of it.
CELLO_RECOVERY_RETRY_MS 1000 Dead-owner recovery retry backoff in milliseconds.
CELLO_RECOVERY_RETRIES 240 Recovery retries before a request fails.
CELLO_SHUTDOWN_TOTAL_MS 40000 The complete stop bound. The drain-token wait is 3/4 of it and the handoff no-progress interval is 5/8.
CELLO_RELEASES 128 Concurrent complete handoffs.
CELLO_READY_FLEET_GATE_MS 120000 The first-readiness gate deadline; 0 disables the gate.
CELLO_MAX_ASSET_FILE_BYTES 25 MiB Per-file static asset limit.
CELLO_MAX_DYNAMIC_WORKER_CODE_BYTES 64 MiB Loaded dynamic module total.

An L1 compaction merges at most 256 source objects within a 64 MiB buffer. A larger source object spills to temporary files in the cell’s local LTX directory, so the node needs free disk for the source and the output.

Removed settings

Remove these from the environment, including an empty value or the former default. Cello refuses to start when any one of them is set:

Removed setting Current behavior
CELLO_OUTPUT_GATE Cello always waits for the durability proof before it acknowledges a write.
CELLO_SHUTDOWN_DRAIN_MS, CELLO_DRAIN_TOKEN_WAIT_MS Rejected at startup. Use CELLO_SHUTDOWN_TOTAL_MS.
CELLO_OTEL_SINK Set CELLO_OTEL=1 for the fleet bucket, or CELLO_OTEL to the collector base URL.
CELLO_AI_BINDING, CELLO_AI_URL The AI adapter is removed. Call the provider from application code.
CELLO_CLOUD_RESTART_ON_DEPLOY A managed deployment adopts the new code in place.
CELLO_STORAGE_PROBE A node always checks the storage contract.
CELLO_EVICTIONS A node runs at most four concurrent evictions.
CELLO_LOG_CAPTURE_WORKERS A node uses at most eight log capture workers.
CELLO_REBALANCE_BATCH_CELLS A balancing batch moves at most 32 idle cells.
CELLO_PRESENCE_SHADOW Use cello diagnose --read-only to check leases.
CELLO_LOG_BUNDLE Fleet durability always bundles uploads.
CELLO_QUEUE_PRODUCER_GROUP_MS A Queue owner groups producer calls with a 4 ms timer.
CELLO_LOG_GROUP_COMMIT_MS A node waits 1 ms before a fleet log capture when Queue writes are pending.
CELLO_PACED_HANDOFF A node always attempts the handoff within CELLO_SHUTDOWN_TOTAL_MS.

Was this page helpful?