# How Tuning Parameters Affect celld Performance: Complete Environment Variable Guide

> Optimize celld performance by mastering environment variables. Understand how tuning parameters for memory, concurrency, timeouts, and durability impact throughput, latency, and stability.

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

---

**celld performance is controlled entirely through environment variables that govern memory pressure, concurrency limits, operation timeouts, durability guarantees, and background compaction—each parameter creates explicit trade-offs between throughput, latency, and stability.**

The celld runtime, maintained by the Deno team at `denoland/celld`, exposes its operational behavior through a set of tuning knobs defined as environment variables. These parameters directly configure resource allocation, execution limits, and durability semantics. Understanding how each parameter affects celld performance allows operators to optimize deployments for their specific workload characteristics.

## Memory Pressure and Resident Cell Limits

### CELLD_MAX_RSS_MB: Memory High-Water Mark

**`CELLD_MAX_RSS_MB`** sets the upper bound for in-use memory that cells may occupy, functioning as the high-water mark for memory-pressure shedding. The value is parsed by `PressureConfig::from_limits` in [`crates/logic/pressure.rs`](https://github.com/denoland/celld/blob/main/crates/logic/pressure.rs).

- **Lower values** force earlier shedding, reducing OOM risk but limiting work kept in memory, which lowers throughput
- **Higher values** allow more cells to remain alive, increasing throughput at the cost of elevated memory pressure

### CELLD_MAX_RESIDENT_CELLS: Hard Concurrency Cap

**`CELLD_MAX_RESIDENT_CELLS`** imposes a hard limit on resident cells admitted simultaneously. The check occurs in `State::has_capacity` within [`crates/logic/cell.rs`](https://github.com/denoland/celld/blob/main/crates/logic/cell.rs).

- **Tightening the cap** throttles active cell concurrency, reducing CPU and I/O load but limiting parallelism
- **Loosening the cap** raises concurrency, improving latency under load but potentially increasing contention and memory consumption

## Cold-Start and Activation Behavior

### CELLD_ACTIVATIONS: Concurrent Cold-Start Limit

**`CELLD_ACTIVATIONS`** controls the maximum number of concurrent cold-cell activations, defaulting to `min(CPU, 128)`. This semaphore is implemented in `runtime::activation_semaphore` in [`crates/celld/runtime.rs`](https://github.com/denoland/celld/blob/main/crates/celld/runtime.rs).

- **Reducing the limit** smooths CPU/IO spikes during mass cell starts, at the expense of slower cold-start latency
- **Raising the limit** enables parallel cell spin-up, improving cold-start latency but risking CPU oversubscription

## Operation Timeout and Responsiveness

### CELLD_OPERATION_DEADLINE_MS: Global Operation Timeout

**`CELLD_OPERATION_DEADLINE_MS`** sets the global timeout for non-restore operations, defaulting to 15 seconds. Enforcement happens in `runtime::run_operation` in [`crates/celld/runtime.rs`](https://github.com/denoland/celld/blob/main/crates/celld/runtime.rs).

- **Shorter deadlines** abort long-running work sooner, maintaining node responsiveness under heavy load, but may fail legitimate long operations
- **Longer deadlines** allow heavy jobs to complete, at the risk of hung nodes under overload conditions

## Durability and Write Performance

### CELLD_OUTPUT_GATE: Write Durability Barrier

**`CELLD_OUTPUT_GATE`** (default `1`) controls whether each write is acknowledged only after becoming durable in the replication log. The implementation resides in `replication::write` in [`crates/celld/replication.rs`](https://github.com/denoland/celld/blob/main/crates/celld/replication.rs).

- **Enabled (`1`)**: Guarantees strong durability but adds write latency
- **Disabled (`0`)**: Reduces latency and improves write throughput, with the risk of losing recent writes on crash

## Worker Pool and Sandbox Memory

### CELLD_MAX_LOADED_WORKERS: Loaded Worker Cache Size

**`CELLD_MAX_LOADED_WORKERS`** limits workers kept loaded in the sandbox, defaulting to 256. The check occurs in `worker_loader::load_worker` in [`crates/celld/worker_loader.rs`](https://github.com/denoland/celld/blob/main/crates/celld/worker_loader.rs).

- **Lower limits** reduce memory pressure from loaded workers, improving overall memory availability
- **Higher limits** enable more concurrent workers, increasing parallelism but raising memory consumption

## LTX Compaction and Storage Optimization

### CELLD_LTX_COMPACTION Family

The compaction parameters control additive L1 object creation and L1 compaction concurrency:

- **`CELLD_LTX_COMPACTION`**: Master enable/disable flag
- **`CELLD_LTX_COMPACTION_MIN_TXIDS`**: Minimum transaction ID threshold before compaction triggers
- **`CELLD_LTX_COMPACTIONS`**: Concurrency of compaction attempts

These are implemented in `ltx::compaction` within [`crates/ltx/lib.rs`](https://github.com/denoland/celld/blob/main/crates/ltx/lib.rs).

- **Disabling compaction (`0`)** reduces background CPU/I/O but increases read-amplification over time
- **Adjusting min-TXID and concurrency** balances L1 creation rate against write latency and storage churn

## Observability Overhead

### CELLD_OTEL and Related Variables

The telemetry system exports internal events via OpenTelemetry:

- **`CELLD_OTEL`**: Master enable flag
- **`CELLD_OTEL_SINK`**: Export destination (e.g., `otlp`)
- **`CELLD_OTEL_FLUSH_MS`**: Flush interval in milliseconds
- **`CELLD_OTEL_FLUSH_BYTES`**: Flush threshold by byte size

Implementation is in [`crates/celld/telemetry.rs`](https://github.com/denoland/celld/blob/main/crates/celld/telemetry.rs).

- **Enabling telemetry** adds CPU and network overhead proportional to event volume
- **Tuning flush intervals and sizes** trades observability data freshness for resource consumption

## Practical Configuration Examples

### Low-Memory, High-Throughput Profile

```bash
export CELLD_MAX_RSS_MB=4096
export CELLD_MAX_RESIDENT_CELLS=2000
export CELLD_ACTIVATIONS=64
export CELLD_OUTPUT_GATE=0
export CELLD_MAX_LOADED_WORKERS=64

```

### Production Durability Profile

```bash
export CELLD_MAX_RSS_MB=16384
export CELLD_MAX_RESIDENT_CELLS=8000
export CELLD_ACTIVATIONS=128
export CELLD_OPERATION_DEADLINE_MS=30000
export CELLD_OUTPUT_GATE=1
export CELLD_MAX_LOADED_WORKERS=256

```

### Development Telemetry Profile

```bash
export CELLD_OTEL=1
export CELLD_OTEL_SINK=otlp
export CELLD_OTEL_FLUSH_MS=10000
export CELLD_OTEL_FLUSH_BYTES=1048576

```

Store configurations in a `.env` file for loading before startup:

```bash

# .env

CELLD_MAX_RSS_MB=8192
CELLD_MAX_RESIDENT_CELLS=3000
CELLD_ACTIVATIONS=128

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`crates/logic/pressure.rs`](https://github.com/denoland/celld/blob/main/crates/logic/pressure.rs) | Memory-pressure classification and shedding via `PressureConfig::classify` |
| [`crates/celld/runtime.rs`](https://github.com/denoland/celld/blob/main/crates/celld/runtime.rs) | Activation limits, operation deadlines, request routing |
| [`crates/celld/replication.rs`](https://github.com/denoland/celld/blob/main/crates/celld/replication.rs) | Output gate durability control |
| [`crates/ltx/lib.rs`](https://github.com/denoland/celld/blob/main/crates/ltx/lib.rs) | LTX compaction parameter handling |
| [`crates/celld/telemetry.rs`](https://github.com/denoland/celld/blob/main/crates/celld/telemetry.rs) | OpenTelemetry export implementation |
| [`crates/celld/worker_loader.rs`](https://github.com/denoland/celld/blob/main/crates/celld/worker_loader.rs) | Dynamic worker loading and cache limits |

## Summary

- **Memory pressure parameters** (`CELLD_MAX_RSS_MB`, `CELLD_MAX_RESIDENT_CELLS`) protect against OOM at the cost of potential throughput reduction when limits are tight
- **Concurrency controls** (`CELLD_ACTIVATIONS`, `CELLD_MAX_LOADED_WORKERS`) balance resource saturation against latency under load
- **Durability semantics** (`CELLD_OUTPUT_GATE`) offer a direct latency-versus-safety trade-off
- **Timeouts and deadlines** (`CELLD_OPERATION_DEADLINE_MS`) ensure responsiveness but may terminate legitimate work
- **Background processes** (LTX compaction) and **observability** (OpenTelemetry) consume resources proportionally to their configuration aggressiveness

## Frequently Asked Questions

### What happens when celld exceeds CELLD_MAX_RSS_MB?

When the in-use memory crosses the `CELLD_MAX_RSS_MB` threshold, `PressureConfig::classify` triggers shedding. The node removes cells until memory drops to approximately 80% of the crossing point. This protects the process from OOM kills while maintaining partial availability.

### Should I disable CELLD_OUTPUT_GATE for better performance?

Disabling `CELLD_OUTPUT_GATE` improves write throughput and reduces latency by removing the durability wait. Only disable it when potential data loss on crash is acceptable—typically in development environments or for non-critical caching workloads.

### How do I choose the right CELLD_ACTIVATIONS value?

Start with the default `min(CPU, 128)`. Reduce it if you observe CPU throttling or I/O saturation during cold-start spikes. Increase it only on high-core-count machines where parallel cell initialization outweighs oversubscription risks.

### Does enabling OpenTelemetry significantly impact celld performance?

OpenTelemetry export adds CPU overhead for event serialization and network overhead for transmission. The impact scales with event volume and flush frequency. Use `CELLD_OTEL_FLUSH_MS` and `CELLD_OTEL_FLUSH_BYTES` to batch exports and reduce per-event overhead in production.