Complete Guide to Celld Environment Variables: Configuration and Effects

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 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 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 (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 at line 68.

Practical Configuration Examples

Set these variables in your shell before launching celld:

# 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, js.rs, control_plane.rs, and 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 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 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}