Open-source project
cjdelisle/cjdns avatar
cjdelisle/cjdns

cjdns: an encrypted IPv6 mesh where your address is your public key

An encrypted IPv6 network using public-key cryptography for address allocation and a distributed hash table for routing.

5,422 stars601 forksCGPL-3.0

At a glance

What is it?
cjdns builds a self-configuring encrypted IPv6 network on top of whatever links you can find, using public-key cryptography for addressing and a distributed hash table for routing. It is a serious piece of C and Rust infrastructure with a GPL-3.0 licence and a configuration file you must not lose.
Who is it for?
Adopt cjdns if you want an encrypted IPv6 overlay whose addresses you can verify yourself, and you are willing to build it from source and keep the generated /etc/cjdroute.conf safe, because losing or leaking that file means losing your identity on the network. Do not adopt it if you need a managed control plane, or anonymity, since the README's own peering notes say the default DNS seeder connection reveals that you are running cjdns.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 54 days ago.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • cjdelisle/cjdns5,422 ★ · +10
Star history
Repository2026-09-232026-11-13
cjdelisle/cjdns5.4k5.4k

10 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What cjdns solves, and for whom

The README states the design in one line: cjdns implements an encrypted IPv6 network using public-key cryptography for address allocation and a distributed hash table for routing. Read that as two separate promises. The first is that your IPv6 address is not handed to you by a registry, a DHCP server or an ISP. It is derived from a key pair you hold. The second is that no central router decides how packets reach that address, because a DHT does the lookup instead. The project's own framing is that this gives near-zero-configuration networking and prevents many of the security and scalability issues that plague existing networks.

The intended audience is not the average application developer. It is people who run nodes: mesh operators, home lab owners who want an encrypted path between cheap VPSes, and anyone who wants an IPv6 address that survives moving between physical networks. The README's testimonials are chat quotes, not measurements, but they point at the same use case, reaching machines that are awkward to reach over the public internet. If you only need a VPN between two cloud regions, cjdns is more machinery than that job requires.

How addressing and routing actually work here

The repository layout tells you where the work happens. There is a crypto directory, a dht directory, a switch directory and a wire directory at the top level, plus a rust workspace with two members, rust/cjdns_sys and rust/cjdnstool. The switch is the forwarding core, the dht is the lookup layer, and wire carries the encoded packets. That split matters when you are debugging: a node that cannot find a peer is a DHT and peering problem, while a node that finds peers but cannot pass traffic is a switch or interface problem.

Address allocation and routing are deliberately coupled to the same key material. Because the address is a function of the public key, two nodes can authenticate each other without a certificate authority, and the network does not need a central allocator that could be coerced or exhausted. The DHT then answers the question of where that address currently lives. The trade-off is that routing correctness depends on the DHT being populated and reachable, and the README's own peering section notes that by default cjdns reaches out to a DNS seeder to find peers and connects to them automatically, which exposes the fact that you are running cjdns to the operators of those nodes. Cryptography here gives you authentication and encryption, not anonymity, and the documentation does not pretend otherwise.

Building cjdns from source and generating your first config

The README gives two install paths. Option 1 is cjdns.sh, which provides pre-built binaries for Linux on amd64 and is documented in a separate repository. Option 2 is building from source, which the README describes in more detail and which is what the commands below follow. You need Rust, NodeJS (the README says it is used for building the C code), GCC or Clang, Make and Git.

On a Debian-based system the dependency step is:

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

On macOS the README suggests checking that clang is active with xcode-select --install, then using Homebrew:

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

Then clone and build. The build script is ./do, and the README says to look for the line Build completed successfully, type ./cjdroute to begin setup.

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

Before configuring anything, the README asks Linux users to check the TUN device. A working device reports a bad state rather than missing:

bash
LANG=C cat /dev/net/tun

If the file does not exist, the README gives the mknod sequence to create it, and if you get Permission denied it says you are probably on an OpenVZ-based VPS and should ask your provider to enable the TUN/TAP device.

Configuration is generated once and then reused. The README's command writes it to /etc/cjdroute.conf, and it warns in bold that a lost conf file means you lost your password and connections, and that anyone who connected to you will no longer be able to connect. A compromised conf file means other people can impersonate you.

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

Once running, the README says the admin interface is available at udp://localhost:11234, and that this can be changed in the configuration. To stop the node, the README uses sudo killall cjdroute, with pgrep cjdroute or top to check whether it is still running. Note the README's own warning that this starts cjdns as root so it can configure the system without permission problems; doc/non-root-user.md covers the alternative.

Peering, the DNS seeder, and the clandestine node case

Out of the box you do not choose your peers. The README says cjdns reaches out to a DNS seeder, finds peers and connects automatically. That is what makes the near-zero-configuration claim true, and it is also the point where the privacy story gets narrower than people expect. If you are running a node you would rather not advertise, the README's instruction is to find the dnsSeeds section of the configuration and comment it out, then take peering credentials from a node you want to connect to and add them under the UDPInterface / connectTo section of cjdroute.conf. doc/peering.md covers the details.

This is a real design boundary, not a bug. Automatic discovery trades a small amount of metadata exposure for not having to arrange peer relationships by hand. If that trade is unacceptable for your threat model, you are now maintaining a peer list, which is exactly the operational work cjdns was trying to remove. Decide which of those two you want before you deploy, because switching later means editing a config file that also holds your identity.

Running as root, and the services you did not mean to expose

The README is unusually direct about this: once your node is running, you are a newly minted IPv6 host, and your operating system may automatically reconfigure network services to use the new address. It tells you to check that you are not offering more services than you intended and points at doc/network-services.md. This is the failure mode most likely to bite someone who treats cjdns as a drop-in VPN. A VPN gives you an interface; cjdns gives you a routable address on a network with other participants, and any daemon that binds to all interfaces may now be reachable over it.

The second constraint is the root requirement. The README's start command runs cjdroute as root, and it explicitly notes this is so the process can configure the system without concern for permissions. That is a large amount of privilege for a network daemon written in C with a Rust component. doc/non-root-user.md exists precisely because this is a known concern, and reading it before deployment is cheaper than retrofitting it later.

A third limitation is portability. The install instructions are written for Linux distributions and macOS, and the README says they should be informative enough for other distributions but should not be expected to work verbatim. The top-level Dockerfile points to contrib/docker/Dockerfile.

cjdns compared with Yggdrasil

The comparison people reach for is Yggdrasil, and the difference is worth stating precisely because both projects derive IPv6 addresses from cryptographic keys. The shared idea is that identity and address are the same thing, so no central allocator is needed. Where they diverge is the routing layer. cjdns, as its README says, uses a distributed hash table for routing, with the dht and switch directories in this repository implementing that path.

That difference has practical consequences you can reason about without benchmarks. A DHT-based design has to maintain and query a distributed index, which is more moving parts and more state to converge, but it does not force traffic through a tree topology. A tree-based design is simpler to reason about and tends to give more predictable paths, at the cost of concentrating traffic through the tree structure. Neither is strictly better; they fail differently under churn and under partition. If you are choosing between them, the useful question is which failure mode you can debug at 2am with the tooling each project ships.

cjdns is written primarily in C with a Rust workspace alongside it, which is a different maintenance surface than a project written entirely in Go. That shows up in the build: you need NodeJS to build the C code and Rust for the workspace members, so your build machine carries two toolchains before it carries one compiler.

Maintenance, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-09-22. That is recent enough that the project is being worked on, but the repository has no published releases, so there is no versioned release cadence to plan around. package.json carries version 0.17.3. If you deploy cjdns, plan on tracking the master branch rather than waiting for tagged releases.

Upgrade cost is dominated by the configuration file, not the binary. Because /etc/cjdroute.conf holds the key material that determines your address, replacing the binary is straightforward but regenerating the config is not: the README states that a lost conf file means you lost your password and connections, and anyone who connected to you can no longer connect. Back that file up somewhere you control before you touch the installation, and treat it as a secret rather than a config.

The licence is GPL-3.0. The practical implication for most readers is that if you distribute a modified cjdroute binary, the GPL's source-availability terms attach to that distribution. Running cjdns on your own machines and connecting to other people's nodes is not distribution in the ordinary sense. This is a description of the licence, not legal advice; if you plan to ship cjdns inside a product, talk to someone qualified about what GPL-3.0 requires of your combined work.

Editorial conclusion

Adopt cjdns if you want an encrypted IPv6 overlay whose addresses you can verify yourself, and you are willing to build it from source and keep the generated /etc/cjdroute.conf safe, because losing or leaking that file means losing your identity on the network. Do not adopt it if you need a managed control plane, or anonymity, since the README's own peering notes say the default DNS seeder connection reveals that you are running cjdns. Verify /dev/net/tun exists and is usable before anything else, and read doc/network-services.md before you leave the node running as root.

Frequently asked questions

What is the cjdns network and how is it different from a normal VPN?

cjdns is an encrypted IPv6 network that uses public-key cryptography for address allocation and a distributed hash table for routing, so your address comes from your key rather than from a server. A VPN typically gives you an interface into someone else's network; cjdns makes you a routable host on a peer-to-peer network with other participants.

How do I install cjdns on Linux or macOS?

The README gives two options: pre-built amd64 Linux binaries via cjdns.sh, or building from source. The source path needs Rust, NodeJS, GCC or Clang, Make and Git, then git clone, cd cjdns and ./do, followed by generating a config with ./cjdroute --genconf.

What happens if I lose my cjdroute.conf file?

The README warns that a lost conf file means you lost your password and connections, and anyone who connected to you will no longer be able to connect. It also warns that a compromised conf file lets other people impersonate you on the network.

Does cjdns hide the fact that I am running a node?

Not by default. The README states that cjdns reaches out to a DNS seeder to find peers and connects automatically, which exposes the fact that you are running cjdns to the operators of those nodes. It suggests commenting out the dnsSeeds section and adding explicit peering credentials under UDPInterface / connectTo if you want a clandestine node.

Official sources

  1. cjdelisle/cjdns on GitHub
  2. Issues
  3. License: GPL-3.0
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/cjdelisle-cjdns.svg)](https://hysenlabs.com/projects/cjdelisle-cjdns)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/cjdelisle-cjdns.svg)](https://hysenlabs.com/projects/cjdelisle-cjdns)

Was this useful?