# Complete Guide to Celld Environment Variables: Configuration and Effects

> Discover celld environment variables that control timeouts, resource limits, and more. Configure celld behavior easily without code changes using this comprehensive guide.

- Repository: [Deno/celld](https://github.com/denoland/celld)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Celld reads over 40 environment variables at startup to configure timeouts, resource limits, storage backends, and testing hooks without requiring code changes.**

The `denoland/celld` runtime is designed for high configurability through environment variables. Operators can tune everything from V8 heap limits to S3-compatible storage endpoints by setting specific variables before invoking the binary. This guide catalogs every environment variable recognized by the source code, organized by functional area, with references to the exact file locations where they are parsed via `std::env::var`.

## Core Runtime and Identity

### Node Identification and Environment

**`CELLD_NODE`** defines the identifier for the current node, defaulting to a random UUID if unset. This value is read in [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/crates/celld/main.rs) at line 4540.

**`CELLD_INSTANCE_NAME`** provides a human-readable name for the instance, falling back to the system hostname when omitted (see [`crates/celld/control_plane.rs`](https://github.com/denoland/celld/blob/main/crates/celld/control_plane.rs) line 2745). **`CELLD_ENV`** specifies the deployment environment (e.g., `"production"`), defaulting to `"dev"` if not provided (control_plane.rs line 2450).

### Configuration Paths and Threads

**`CELLD_CONFIG_DIR`** sets the directory for configuration files, cascading to XDG standards or `$HOME` if undefined (control_plane.rs lines 2457–2461). To control the async runtime, set **`CELLD_TOKIO_THREADS`** to cap the maximum number of Tokio worker threads (main.rs line 4370).

## Timeouts and Cell Lifecycle

Cell lifetime and leasing behavior are governed by several time-based variables.

**`CELLD_TTL_MS`** overrides the default time-to-live for cells in milliseconds (main.rs line 847). **`CELLD_OPERATION_DEADLINE_MS`** establishes a global deadline for operations (main.rs line 879), while **`CELLD_ALARM_RESIDENT_MS`** in [`crates/celld/wake.rs`](https://github.com/denoland/celld/blob/main/crates/celld/wake.rs) (line 31) controls how long a resident alarm stays active.

For clustering, **`CELLD_LAZY_NODE_LEASE`** enables lazy-node leasing mode when set to `"1"` (main.rs line 851), and **`CELLD_LEASE_LINGER_MS`** determines how long a lease persists after a node disappears (main.rs line 856).

## Resource Governance and Scaling

### Memory and Execution Limits

Hard limits prevent runaway resource consumption. **`CELLD_MAX_RSS_MB`** sets an upper bound on RSS memory usage before throttling occurs (main.rs line 5336). For the V8 engine, **`CELLD_V8_HEAP_LIMIT_MB`** constrains the heap size in MiB (js.rs line 2095), and **`CELLD_HANDLER_BUDGET_S`** defines the maximum execution time in seconds before a handler is aborted (js.rs line 894).

### Worker and Cell Concurrency

Scaling parameters control concurrency. **`CELLD_MAX_RESIDENT_CELLS`** limits the total number of resident cells (main.rs line 4469), while **`CELLD_MAX_COHOSTED`** restricts how many cells can run per process (main.rs line 4591). For worker loading, **`CELLD_MAX_LOADED_WORKERS`** caps simultaneous workers (js.rs line 3248), and **`CELLD_WORKERS`** sets the number of logical workers to start (main.rs line 4543).

Additional tuning includes **`CELLD_LOAD_SAMPLE_MS`** for load statistic sampling intervals (main.rs line 4880) and **`CELLD_PRESSURE_OWNERSHIP`** for ownership-related pressure handling (main.rs line 5263).

## Networking and Cluster Communication

**`CELLD_ADVERTISE`** overrides the address advertised to peers, defaulting to the listen address (main.rs line 861). To limit connection saturation, set **`CELLD_MAX_OUTBOUND_WEBSOCKETS`** (main.rs line 887) and **`CELLD_FETCH_TIMEOUT_S`** for global HTTP fetch timeouts (js.rs line 3675).

Cluster presence is managed via **`CELLD_PRESENCE_HEARTBEAT_MS`**, setting the heartbeat interval (control_plane.rs line 920), and **`CELLD_PRESENCE_SHADOW`**, which enables shadow presence when set to `"on"` for testing scenarios (control_plane.rs line 928).

## Storage and Caching Backends

### Content-Addressable Store (CAS)

The CAS integration requires several variables. **`CELLD_CAS_LIVE`** must be set to `"1"` to enable writes (bucket.rs line 321). **`CELLD_CAS_BUCKET`** specifies the required bucket name (bucket.rs line 324), with **`CELLD_CAS_ENDPOINT`** providing an optional custom endpoint (bucket.rs line 325).

Authentication leverages standard AWS variables: **`AWS_ACCESS_KEY_ID`**, **`AWS_SECRET_ACCESS_KEY`**, and **`AWS_SESSION_TOKEN`** (bucket.rs lines 328–330). For S3-compatible stores, **`S3_ENDPOINT`** overrides the default endpoint (ownership_store.rs line 138), and region is determined by **`AWS_REGION`** or **`AWS_DEFAULT_REGION`** (ownership_store.rs lines 139–141).

### Local and Asset Caching

**`CELLD_LOCAL_CACHE_MAX_BYTES`** limits the local cache size (main.rs line 5372). For asset caching, **`CELLD_ASSET_CACHE_DIR`** specifies the directory (assets.rs line 104) and **`CELLD_ASSET_CACHE_BYTES`** sets the maximum byte limit (assets.rs line 109).

## AI Integration

External AI services are configured via **`CELLD_AI_URL`**, which sets the service endpoint (js.rs line 6824). When this URL is defined, **`CELLD_AI_BINDING`** optionally names the binding, defaulting to `"AI"` if omitted (fleet.rs lines 452–453).

## Testing and Debug Utilities

Celld includes extensive testing hooks. **`CELLD_VALIDATE`** disables runtime validation checks when set to `"0"` (main.rs line 924), and **`CELLD_OUTPUT_GATE`** disables the output gate when set to `"0"` for test isolation (main.rs line 4853).

Startup behavior is controlled by **`CELLD_TEST_CELL_STARTUP_BARRIER`**, which blocks cell startup until released (runtime.rs line 1162), and **`CELLD_TEST_CELL_STARTUP_FAILURE`**, which forces a startup failure when set to `"1"` (runtime.rs line 1174).

Additional test variables include:
- **`CELLD_TEST_GENERATION`** for deterministic generation IDs (main.rs line 863)
- **`CELLD_TEST_FAIL_PUBLISH_ONCE`** to simulate a single publish failure (main.rs line 4478)
- **`CELLD_TEST_DATA_DIR`** and **`CELLD_WATCH`** for temporary data and watch modes (main.rs line 4556)
- **`CELLD_TEST_SCRIPT_PATH`** for startup scripts (main.rs line 4681)
- **`CELLD_TEST_DO_CLASSES`** and **`CELLD_TEST_DO_BINDINGS`** for class and binding features (main.rs lines 4683 and 4690)

## Build and Deployment Configuration

**`CELLD_ESBUILD`** specifies the path to the `esbuild` binary used for JavaScript bundling (deploy.rs line 1079). **`CELLD_VARS_FILE`** points to a file containing `NAME=VALUE` pairs imported into the environment (fleet.rs line 504).

For cloud compatibility, **`CELLD_CLOUD_RESTART_ON_DEPLOY`** forces a worker restart after each deployment (control_plane.rs line 36). Custom worker loading is supported via **`CELLD_WORKER_LOADER`** (main.rs line 4341).

## Security and Re-execution

**`REEXEC_SIGNER_ENV`** names the environment variable containing a re-execution signer token, referenced in [`crates/celld/peer_probe.rs`](https://github.com/denoland/celld/blob/main/crates/celld/peer_probe.rs) at line 68.

## Practical Configuration Examples

Set these variables in your shell before launching `celld`:

```bash

# Basic runtime tuning

export CELLD_TTL_MS=30000
export CELLD_TOKIO_THREADS=8
export CELLD_NODE="unique-node-id-123"

# Resource limits

export CELLD_V8_HEAP_LIMIT_MB=512
export CELLD_MAX_RSS_MB=1024
export CELLD_HANDLER_BUDGET_S=10

# CAS Storage configuration

export CELLD_CAS_LIVE=1
export CELLD_CAS_BUCKET=my-production-bucket
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=secret...

# Testing configuration

export CELLD_VALIDATE=0
export CELLD_TEST_CELL_STARTUP_BARRIER=1

```

## Summary

- **Celld environment variables** provide granular control over runtime behavior without code modification.
- Key configuration areas include **node identity**, **resource limits** (V8 heap, RSS, workers), **storage backends** (CAS/S3), and **networking** (websockets, fetch timeouts).
- Testing hooks like `CELLD_TEST_CELL_STARTUP_BARRIER` and `CELLD_TEST_CELL_STARTUP_FAILURE` enable robust failure injection.
- Variables are parsed primarily in [`main.rs`](https://github.com/denoland/celld/blob/main/main.rs), [`js.rs`](https://github.com/denoland/celld/blob/main/js.rs), [`control_plane.rs`](https://github.com/denoland/celld/blob/main/control_plane.rs), and [`bucket.rs`](https://github.com/denoland/celld/blob/main/bucket.rs) using `std::env::var`.

## Frequently Asked Questions

### How do I increase the V8 heap limit in celld?

Set the **`CELLD_V8_HEAP_LIMIT_MB`** environment variable to the desired size in megabytes. According to [`crates/celld/js.rs`](https://github.com/denoland/celld/blob/main/crates/celld/js.rs) at line 2095, this value directly constrains the V8 isolate heap before garbage collection pressure triggers.

### Which variable disables runtime validation checks?

Set **`CELLD_VALIDATE=0`**. As implemented in [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/crates/celld/main.rs) at line 924, this string comparison disables internal validation assertions, which is useful for performance testing but not recommended for production.

### How do I configure celld to use MinIO or another S3-compatible store?

Define **`CELLD_CAS_LIVE=1`**, **`CELLD_CAS_BUCKET`** with your bucket name, and **`S3_ENDPOINT`** with your custom URL (ownership_store.rs line 138). Provide credentials via **`AWS_ACCESS_KEY_ID`** and **`AWS_SECRET_ACCESS_KEY`** (bucket.rs lines 328–330).

### What is the difference between CELLD_NODE and CELLD_INSTANCE_NAME?

**`CELLD_NODE`** sets the unique machine-readable node identifier used for cluster consensus (main.rs line 4540), while **`CELLD_INSTANCE_NAME`** provides a human-readable label for logging and monitoring that defaults to the system hostname (control_plane.rs line 2745).