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

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.

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.

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:

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.

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)
• crates/logic — the pure coordination protocol with no I/O (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.

# 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:

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.

Memory and V8 Heap Limits

Prevent runaway resource consumption during development:

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:

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

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

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

Start a Fleet Node

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.

Verifying Your Setup: Running Tests

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

cargo test --workspace

Key test categories (documented in 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	Main library: CLI entry, node lifecycle, core types
crates/celld/cli_options.rs	Command-line flags: --bucket, --listen, --advertise
crates/celld/env_vars.rs	Environment parsing for memory limits and configuration
crates/logic/lib.rs	Pure decision core: LTX replication, lease handling, no I/O
crates/logic/peer.rs	HTTP peer transport and authentication
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 for the full list of tunable parameters.

Can I modify the core replication protocol?

Yes. The coordination logic lives in crates/logic/lib.rs as a pure, I/O-free core. Modify it, then rebuild with cargo build --release. The crates/logic/peer.rs file handles the actual network transport if you need to change wire formats or authentication.

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