# How to Set Up a Development Environment for denoland/celld: A Complete Guide

> Set up a denoland/celld development environment easily. Install Rust and Deno, build from source or download a binary, and run `celld dev` for a local node. Get started now.

- Repository: [Deno/celld](https://github.com/denoland/celld)
- Tags: getting-started
- Published: 2026-09-05

---

**To set up a denoland/celld development environment, install Rust and Deno, either download a pre-built binary with `curl -fsSL https://celld.dev/install.sh | sh` or build from source with `cargo build --release`, then run `celld dev` to start a local node without any cloud bucket configuration.**

`celld` is a self-hosted daemon that runs Cloudflare Workers and Durable Objects on ordinary machines. Each machine runs a **node**—a single `celld` process that embeds V8, executes Wrangler bundles, and coordinates with a **fleet** through shared bucket storage. This guide walks through installing the toolchain, building from source, and running your first local development node based on the official denoland/celld repository structure.

## Prerequisites: Rust, Cargo, and Deno

Before building or running `celld`, you need three core tools installed on your system.

### Install Rust and Cargo

`celld` is written in Rust. The build system relies on Cargo for dependency management and compilation.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

```

This installs `rustc`, `cargo`, and the standard toolchain. Verify with `cargo --version`.

### Install Deno

Deno provides the Workers runtime and tooling ecosystem that `celld` integrates with.

```bash
curl -fsSL https://deno.land/install.sh | sh

```

Deno is required for bundling Worker code and running compatibility tests.

## Installation Options: Pre-built Binary vs. Building from Source

You have two paths to obtain the `celld` binary. Choose based on whether you need to modify the source code.

### Option 1: Quick Install with Pre-built Binary

For most users, the install script downloads the correct binary for your platform:

```bash
curl -fsSL https://celld.dev/install.sh | sh

```

The installer places `celld` in `~/.local/bin` and updates your shell profile.

### Option 2: Build from Source

Clone the repository and compile the full workspace. This is necessary when hacking on the core protocol or daemon implementation.

```bash
git clone https://github.com/denoland/celld.git
cd celld
cargo build --release

```

The release binary lands at `target/release/celld`. The build includes:

- `crates/celld` — the daemon CLI and node lifecycle ([`crates/celld/lib.rs`](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs))
- `crates/logic` — the pure coordination protocol with no I/O ([`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs))

## Running a Local Development Node

The `celld dev` command starts a single-node environment with no external dependencies. This is the recommended workflow for iterating on Worker code.

```bash

# If built from source

./target/release/celld dev

# Or if installed via script

celld dev

```

By default, the dev node:

- Stores state in `.celld/dev` (local object store, no S3/GCS required)
- Serves Workers on `http://127.0.0.1:9876`
- Watches source files and rebuilds automatically

### Exposing to Non-Localhost Interfaces

To bind a different address for testing from other machines:

```bash
celld dev --host 0.0.0.0

```

## Configuring Environment Variables and Runtime Limits

`celld` reads configuration from environment variables at startup, parsed in [`crates/celld/env_vars.rs`](https://github.com/denoland/celld/blob/main/crates/celld/env_vars.rs).

### Memory and V8 Heap Limits

Prevent runaway resource consumption during development:

```bash
export CELLD_MAX_RSS_MB=2000          # Total memory threshold (80% default)

export CELLD_V8_HEAP_LIMIT_MB=256     # Per-isolate heap limit (128 MiB default)

export CELLD_MAX_RESIDENT_CELLS=1000  # Cells kept in memory

celld dev

```

When limits are exceeded, `celld` evicts cells according to its LRU policy.

### Log Coloring

Force colored output regardless of TTY detection:

```bash
export FORCE_COLOR=1

# Or disable entirely

export NO_COLOR=1

```

`NO_COLOR` takes precedence when both are set.

## Connecting to a Cloud Bucket (Production Setup)

When you're ready to test fleet behavior or deploy persistently, configure bucket access. `celld` supports S3, GCS, and Azure Blob through the `--bucket` flag.

### Deploy to a Remote Bucket

```bash
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

celld deploy . --bucket s3://my-cells-bucket

```

### Start a Fleet Node

```bash
celld --bucket s3://my-cells-bucket \
      --listen 0.0.0.0:8080 \
      --internal-listen 10.0.0.12:8081 \
      --advertise node-a.internal:8081

```

The `--internal-listen` address handles peer-to-peer replication via the **LTX log format**, while `--listen` serves Worker HTTP requests. Internode traffic uses HMAC-signed requests defined in [`crates/logic/peer.rs`](https://github.com/denoland/celld/blob/main/crates/logic/peer.rs).

## Verifying Your Setup: Running Tests

The test suite validates durability guarantees, exclusive cell ownership, and Cloudflare API compatibility.

```bash
cargo test --workspace

```

Key test categories (documented in [`docs/testing.md`](https://github.com/denoland/celld/blob/main/docs/testing.md)):

- **Differential tests** — compare `celld` behavior against Cloudflare's production runtime
- **Simulation tests** — inject faults and network partitions
- **Live-fleet tests** — validate multi-node consensus under real conditions

## Key Source Files for Developers

Understanding the codebase structure helps when debugging or extending `celld`:

| File | Purpose |
|------|---------|
| [`crates/celld/lib.rs`](https://github.com/denoland/celld/blob/main/crates/celld/lib.rs) | Main library: CLI entry, node lifecycle, core types |
| [`crates/celld/cli_options.rs`](https://github.com/denoland/celld/blob/main/crates/celld/cli_options.rs) | Command-line flags: `--bucket`, `--listen`, `--advertise` |
| [`crates/celld/env_vars.rs`](https://github.com/denoland/celld/blob/main/crates/celld/env_vars.rs) | Environment parsing for memory limits and configuration |
| [`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs) | Pure decision core: LTX replication, lease handling, no I/O |
| [`crates/logic/peer.rs`](https://github.com/denoland/celld/blob/main/crates/logic/peer.rs) | HTTP peer transport and authentication |
| [`examples/hello/index.js`](https://github.com/denoland/celld/blob/main/examples/hello/index.js) | Minimal Worker for testing `celld dev` |

## Summary

- **Install dependencies**: Rust/Cargo and Deno are required for any development workflow
- **Get the binary**: Use `curl -fsSL https://celld.dev/install.sh | sh` for speed, or `cargo build --release` to hack on source
- **Run locally**: `celld dev` gives you a zero-config development node on port 9876
- **Configure limits**: Set `CELLD_MAX_RSS_MB`, `CELLD_V8_HEAP_LIMIT_MB`, and `CELLD_MAX_RESIDENT_CELLS` to control resource usage
- **Scale out**: Add `--bucket s3://...` and `--advertise` flags to join a multi-node fleet with persistent storage
- **Verify**: Run `cargo test --workspace` to ensure your build passes the full durability and compatibility suite

## Frequently Asked Questions

### What is the fastest way to start developing with celld?

Run `curl -fsSL https://celld.dev/install.sh | sh` to install the binary, then `celld dev` in your project directory. This starts a local node with file watching and auto-reload in under a minute, no cloud credentials required.

### Do I need a cloud bucket for local development?

No. The `celld dev` command uses a local object store at `.celld/dev` by default. Cloud buckets are only required when running a persistent fleet or testing multi-node replication.

### How do I debug memory issues in celld?

Set `CELLD_MAX_RSS_MB` and `CELLD_V8_HEAP_LIMIT_MB` environment variables to constrain resources and trigger earlier evictions. Check logs for "evicting cell" messages, and review [`crates/celld/env_vars.rs`](https://github.com/denoland/celld/blob/main/crates/celld/env_vars.rs) for the full list of tunable parameters.

### Can I modify the core replication protocol?

Yes. The coordination logic lives in [`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs) as a pure, I/O-free core. Modify it, then rebuild with `cargo build --release`. The [`crates/logic/peer.rs`](https://github.com/denoland/celld/blob/main/crates/logic/peer.rs) file handles the actual network transport if you need to change wire formats or authentication.