cjdns: Encrypted IPv6 Mesh Networking with Public-Key Address Allocation

What cjdns Does and Who It Is For

cjdns creates an encrypted IPv6 network where each participant's address is derived directly from their public key. This design eliminates address allocation by a central authority: you run cjdns, it generates a key pair, and your IPv6 address on the mesh is computed from that public key. Two nodes that know each other's credentials can communicate directly over an encrypted channel, and the distributed hash table handles routing between nodes that are not directly connected.

The practical use cases documented in the README and by community testimonials include reaching servers reliably when the open internet is congested or unreliable, building a private overlay network across geographically separated servers, and running services that are accessible only to cjdns participants. The README includes a testimonial from a user reporting consistently better speeds through cjdns than through their ISP's path, and another noting stability improvements over the open internet for VPS access.

How the Network Works: DHT Routing and Key-Based Addresses

The architecture is described in the project documentation linked from the README: a Whitepaper at doc/Whitepaper.md explains the design in detail. The key points from the README are that address allocation is automatic from the public key, routing uses a distributed hash table so no central routing table is maintained, and the entire path between any two nodes is encrypted.

This differs from traditional IP networking, where addresses are assigned by IANA, RIRs and ISPs through a hierarchical system, and routing depends on BGP announcements across autonomous systems. cjdns replaces all of that with cryptographic identity and DHT-based path discovery. The result is described as "near-zero-configuration networking" once an initial peer connection is established.

The admin interface runs at `udp://localhost:11234` by default, configurable in `cjdroute.conf`. Several tools in the contrib/ directory interact with this interface, and the README notes a Python library is available for programmatic access. The NAT gateway documentation at doc/nat-gateway.md covers how to share a cjdns connection with other devices on a local network that are not running the daemon themselves. The codebase is a hybrid of C, Rust and JavaScript. Rust handles cryptographic and routing components in the rust/ subdirectory, with a workspace defined in Cargo.toml that includes the cjdnstool CLI and the cjdns_sys crate. JavaScript is used for the build system of the C components and depends on the nthen and saferphore packages listed in package.json. This multi-language architecture reflects a codebase that has evolved over many years, with newer components written in Rust for memory safety while the core C code remains.

Building and Setting Up cjdns

The build requires Rust, NodeJS (for compiling C code), a GCC or Clang compiler, Make and Git. On Debian-based systems:

sudo apt-get install nodejs git build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Red Hat-based distributions:

sudo dnf install nodejs git
sudo dnf install @development-tools
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On macOS:

xcode-select --install
brew install node git make
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and build:

git clone https://github.com/cjdelisle/cjdns.git cjdns
cd cjdns
./do

The build output ends with the message `Build completed successfully, type ./cjdroute to begin setup.` Generate a configuration file:

./cjdroute --genconf | sudo tee -a /etc/cjdroute.conf

Then start the daemon:

sudo ./cjdroute < /etc/cjdroute.conf

To redirect logs to a file: `sudo ./cjdroute < /etc/cjdroute.conf > cjdroute.log`. To stop the daemon: `sudo killall cjdroute`.

Peering: Automatic DNS Seeding and Manual Configuration

By default, cjdns reaches out to a DNS seeder to find peers and connects automatically. The README notes this exposes the fact that you are running cjdns to the operators of those seeder nodes. For a clandestine node, the README advises commenting out the `dnsSeeds` section of `cjdroute.conf` and manually adding peer credentials to the `UDPInterface` / `connectTo` section.

Manual peering requires exchanging credentials with a node operator. The process is described in doc/peering.md in the repository. The NAT gateway setup for sharing a cjdns connection with other devices on a LAN is documented in doc/nat-gateway.md.

For OpenVZ VPS users, the TUN/TAP device may not be available by default. The README gives the setup command:

sudo mkdir -p /dev/net && sudo mknod /dev/net/tun c 10 200 && sudo chmod 0666 /dev/net/tun

And advises asking the provider to enable the TUN/TAP device if that does not work, describing this as standard protocol for VPS providers.

Running cjdns as a Non-Root User and Securing the Node

The README notes that the default startup command runs cjdroute as root. Instructions for running as a non-root user are in doc/non-root-user.md. Once cjdns is running and your node has an IPv6 address, existing network services on the machine may reconfigure themselves to accept connections on this new address. The README advises checking doc/network-services.md to verify you are not exposing more services than intended.

The configuration file at /etc/cjdroute.conf contains the node's private key. The README warns: "A lost conf file means you lost your password and connections and anyone who connected to you will no longer be able to connect. A compromised conf file means that other people can impersonate you on the network." The file should be protected from unauthorized access.

A Docker deployment is available for containerized setups. The repository includes a Dockerfile based on Alpine 3.6 that builds cjdns from source and runs it with a mounted /etc/cjdns volume.

cjdns Versus Yggdrasil: Two Self-Routing Encrypted Networks

Yggdrasil Network is the closest alternative to cjdns. Both create end-to-end encrypted overlay networks where each node's IPv6 address is derived from a cryptographic key, and both operate without a central routing authority. The routing mechanism differs: cjdns uses a distributed hash table, while Yggdrasil uses a spanning tree routing protocol. The practical difference is that Yggdrasil is more recent, has more thorough current documentation, and supports a wider range of platforms including Android natively.

cjdns has a longer history and was the foundation of the Hyperboria network, the best-known real-world cjdns deployment. The README links to Hyperboria peering resources. Yggdrasil does not have an equivalent named public network in the same way. The cjdns README notes that its clandestine mode configuration (disabling DNS seeder and using manual peer credentials) offers a degree of privacy from network operators that automatic seeder-based connections do not, which is a consideration for users with a specific threat model.

For users choosing between them, Yggdrasil's documentation and platform support are currently stronger. cjdns offers the established Hyperboria community and a more battle-tested codebase for those who want an existing network to join.

Licence, Maintenance and Multi-Language Codebase

cjdns is licensed under GPL-3.0. This means any modified version you distribute must also be open source under GPL-3.0. The daemon and its tools are free to use for personal or commercial purposes without redistribution obligations, but shipping modified builds requires releasing the source.

The codebase is a hybrid of C, Rust and NodeJS. The Rust components are in the rust/ directory with a workspace defined in Cargo.toml, including a cjdnstool utility and the sys crate. NodeJS is used for the build system. The package.json shows dependencies on nthen and saferphore, and the Cargo.toml uses Tokio, serde_json, boringtun (a WireGuard implementation) and trust-dns-resolver among others.

The last push was on 2026-09-22. The project does not publish formal GitHub releases but has active commits. The README is maintained in eleven languages including Russian, German, Spanish, French, Portuguese, Swedish, Greek, Croatian, traditional and simplified Chinese.

Editorial conclusion

cjdns suits privacy-focused individuals, researchers and small communities who want a self-organizing encrypted network independent of ISP infrastructure or central routing authorities. It is not designed for enterprises that need SLA guarantees, centralized management or commercial support. The GPL-3.0 licence means any distributed derivatives must also be open source. Before deploying, verify that your VPS provider allows the TUN/TAP device if running in a virtual machine, and check whether automatic DNS seeder peering is acceptable for your threat model. For a simpler setup with Yggdrasil-level documentation, cjdns's manual configuration is more involved than some alternatives.

Frequently asked questions

Official sources

1. cjdelisle/cjdns on GitHub
2. Issues
3. License: GPL-3.0
4. README