The dendritic network

Running a dendritic node

dendritic-node is the dendritic network's node: one program that stores encrypted pieces of the network's data, carries its anonymous traffic, and gives you a local proxy into it. Everything it does is decided by one JSON config file and a handful of flags. This guide takes you from download to a node that stays up.

1. Install & first run

The node is a single static binary with nothing to install beside it: no router, no proxy, no database server. The anonymous overlay, AXON, is built in.

Download

Not published yet

The prebuilt Linux binary (dendritic-node-linux-amd64, static) will be listed here with its SHA-256 as soon as it is published. Until then, build it from source; it takes a minute.

Build from source

You need Go (1.21 or later fetches the toolchain the module asks for on its own). From the anonymOS source tree:

make dendritic-node        # writes build/dendritic-node

or from the root of the node's own source (the folder holding go.mod):

CGO_ENABLED=0 go build -trimpath -o dendritic-node ./cmd/dendritic-node

CGO_ENABLED=0 is what makes the binary static: no C library to match, so the same file runs on any Linux of that architecture.

First run

./dendritic-node

With no arguments, the node:

  • creates a config file at ~/.config/Rabbiit/storage-node/config.json (mode 0600), along with its S3 credentials and encryption keys in the same directory. On macOS that is ~/Library/Application Support/Rabbiit/storage-node, and on Windows %AppData%\Rabbiit\storage-node;
  • starts as a full storage node, the default role;
  • starts the AXON proxy on 127.0.0.1:4480 and joins the overlay;
  • starts the management page on port 9090, protected by a generated password.

The log names the config file, the dashboard address and the addresses the node serves on AXON. These are the lines to look for:

config /home/you/.config/Rabbiit/storage-node/config.json | payout NOT SET — this node will earn nothing (use --payout 0x…) | dashboard 0.0.0.0:9090 (reachable from your local network, password required)
AXON proxy for .key.axon addresses on http://127.0.0.1:4480
joined the AXON overlay as a client through 1 seed relay(s); 6 relay(s) known
expert: serving /expert for praxis at <56 characters>.key.axon (AXON)

Until the node can reach a relay it logs AXON: could not join (…); retrying in 15s and keeps retrying. That means the network is not reachable yet, not that anything is broken.

The dashboard password

The generated password is not printed. It is the ui_password value in the config file (user admin). Open the file to read it, or replace it with one of your own of at least 12 characters.

Three flags help you find your way around:

./dendritic-node -config /path/to/config.json   # use (or create) a config somewhere else
./dendritic-node -show-config                   # print the effective config, secrets hidden, and exit
./dendritic-node -config-path                   # print where the config file lives, and exit

Back up master.key and metadata.db from the data directory. Without them your own uploaded files cannot be reassembled, and no peer can do it for you. Only one node may use a data directory at a time; a bare timeout at startup means another one already holds it.

2. How configuration works

Everything the node does is in one JSON file. There are no posture flags: you never start it with --gateway or --relay. To change what it does, edit the file (or use the management page, which edits the same file) and restart the node. Most changes take effect at the next start.

The management page

By default ui_listen is 0.0.0.0:9090: every interface, so you can manage a headless box from your laptop. Because of that, a password is required for any address other than loopback; the first run generates one. The page is plain HTTP, and it can change your payout address.

On a machine with a public address

Don't leave the page on 0.0.0.0. Set "ui_listen": "127.0.0.1:9090" to keep it on the machine itself, a private LAN address such as "192.168.1.50:9090", or "" to turn it off (the same as -ui-listen off). A specific public address is refused outright.

Flags

A flag is saved to the config and used from then on, so you pass it once instead of baking it into a service file.

FlagWhat it does
-config <path>Use this config file (created if missing). Its directory becomes the data directory unless data_dir says otherwise.
-config-pathPrint where the config file is and exit.
-show-configPrint the effective config, with secrets hidden, and exit.
-payout 0x…Where credit earnings go. A malformed address is refused, not saved.
-ui-listen <addr>Management page address; off disables it.
-capacity-gib <n>Disk to donate, in GiB.

Environment variables

Three affect only the expert bridge, which serves model inference over the overlay:

VariableWhat it does
RABBIIT_EXPERT_LISTENAddress of the loopback expert API. Default 127.0.0.1:4481.
RABBIIT_EXPERT_BACKENDURL of the expert backend that /expert requests are forwarded to.
RABBIIT_EXPERT_PEERSComma-separated .key.axon expert peers to list in the proxy's peer directory.

3. Pick a role

run_mode decides what the node runs. Change it and restart to switch.

run_modeWhat it doesWhat it needs
storage
default
Stores encrypted shards for the network, serves the storage DHT and a local S3 gateway (s3_listen, with access_key/secret_key), and joins the overlay. Earns through proof of facilitation once payout_address is set. Nothing. Self-contained, and needs no open port.
gateway-only Serves content over HTTPS as one of the network's public front doors. No storage. gateway.enabled: true, gateway.public_hostname, and TLS: gateway.tls.mode = existing (with certificate_path/private_key_path), acme (real DNS and a real acme_email; port 80 open), or reverse_proxy (TLS handled in front of it). Port 443 open to the internet.
probe-only A signed verification vantage point: checks that gateways answer from where you are. No storage. gateway.probe_enabled: true, gateway.enabled: false, gateway.probe_network, a gateway.public_hostname, and a non-privileged gateway.listen_port (e.g. 8443).

Independently of run_mode, a node takes on network roles according to its axon settings:

RoleHow you get itNotes
Storage nodeDefault (run_mode: storage)Stores shards it cannot read and serves the storage DHT.
RelayAutomatic once the node has a reachable address: axon.listen + axon.announceCarries other people's circuits. Opt out with relay_off: true. Stores nothing, learns nothing about what it carries.
ExitOpt-in: axon.exit: trueForwards requests to the open internet. Read the warning first.
Service / expert nodeEvery nodeHosts AXON hidden services, such as its /expert endpoint, reachable by .key.axon address from behind any NAT.

4. The networking block (axon)

This block is the heart of the node: how it joins the overlay, whether it routes for others, and how your browser gets in.

KeyDefaultMeaning
seedsemptyRelay multiaddrs to join through, as /ip4/1.2.3.4/tcp/4001/p2p/12D3Koo…. Bootstrap entry points only: one is enough, and the rest are learned by gossip. Empty means the relays named in the signed bootstrap document.
listenemptyMultiaddrs that accept AXON links, e.g. /ip4/0.0.0.0/udp/4001/quic-v1 and /ip4/0.0.0.0/tcp/4001. Only a relay needs them.
announceemptyThe public ip:port to publish, e.g. 203.0.113.7:4001. With listen, this makes the node a relay.
relay_offfalseStay a pure client even with a reachable address.
relayfalseForce relaying on. Requires listen; the node refuses to start without it.
proxy_listen127.0.0.1:4480The loopback HTTP/CONNECT proxy you point a browser at. Loopback addresses only; "" turns it off.
hops3Circuit length. 3 is anonymous. 2 is faster and not anonymous. 2–4 allowed.
allow_same_networkfalseLets a circuit use relays on one network. For dev/test clusters only; see below.
originemptyThe coordinator's AXON address (<56 base32>.key.axon), if known. Empty uses the one the bootstrap document names.
name_rpc, name_contract, name_suffixes, name_missing_fallback, name_legacy_contractoffName resolution. Section 5.
exit, exit_allow_private, exit_viaoffExit routing. Section 6.
allow_same_network must be false for anonymity

Normally every hop of a circuit has to sit on a different network, so that no single vantage point sees a whole circuit. allow_same_network: true switches that off so a test cluster whose relays share one subnet can form circuits at all. With it on, one observer on that subnet sees every hop. Never set it on a node you want to be anonymous.

Relaying for the network

The overlay exists because volunteers relay for each other, and the more independent relays there are, the less any one of them sees. To relay, forward one port (TCP and UDP) to the machine, allow it in the machine's firewall, and declare it:

"axon": {
  "listen": ["/ip4/0.0.0.0/udp/4001/quic-v1", "/ip4/0.0.0.0/tcp/4001"],
  "announce": ["203.0.113.7:4001"]
}

A node with both listen and announce relays by default. A node behind NAT or CGNAT can't relay. Leave it a client: a relay nobody can reach is a hole in every path built through it.

Join the network

A node joins through any relay in axon.seeds. If seeds is empty it reads the relays from rabbiit's signed bootstrap document, and if that document can't be fetched it carries on with the last relays that worked. The current bootstrap relays:

No public bootstrap relays yet

rabbiit hasn't published public bootstrap relays yet. They will be listed here, and in the signed bootstrap document, when they are. Until then a node joins only through relays you name in axon.seeds, such as relays you run yourself.

5. Reach the network from a browser & resolve names

Point your browser's HTTP proxy at proxy_listen (127.0.0.1:4480). Then http://<56 characters>.key.axon works with no further setup. The address is the service's public key, so it needs no lookup and no certificate authority. Step-by-step browser setup.

The proxy refuses ordinary internet addresses unless you have configured an exit (section 6).

Human names and TLDs

To resolve names like example.axon, give the node a resolver:

KeyMeaning
name_rpcAn Ethereum JSON-RPC URL. Set together with name_contract.
name_contractThe address of the AxonTLD registry on that chain.
name_suffixesExtra TLDs to resolve through the registry, as single labels, e.g. ["com"]. .axon is always included. Needs a current (non-legacy) registry, and the TLD enabled on chain too.
name_missing_fallbackOff by default. When on, and only for an extra suffix, a name the registry definitively reports as unregistered (no owner, no records) may go out through your configured exit_via. Without an exit it is refused. Registered names without an AXON record, malformed answers, RPC errors and failed AXON connections never fall back, and .axon never falls back. Requires name_suffixes.
name_legacy_contracttrue to read an older registry deployed before the current contract: .axon only, one destination per name, no extra suffixes.
"axon": {
  "proxy_listen": "127.0.0.1:4480",
  "name_rpc": "http://127.0.0.1:8545",
  "name_contract": "0x<deployed-registry-address>",
  "name_suffixes": ["com"]
}

Restart the node after changing these.

What name resolution does and doesn't promise
  • You trust your RPC. A lookup is a plain eth_call. The node does not verify storage proofs or chain headers, so a lying RPC can substitute a destination or claim a name is unregistered. It also sees which names you look up. Use an RPC you trust, or your own node.
  • Names are network-local. A name in this registry has no connection to public DNS. Inside the dendritic network, example.com resolves to the AXON identity its registrant set, which says nothing about who owns example.com on the internet.
  • .key.axon bypasses the registry. A self-certifying address is dialled directly, whatever the registry says.

How names, records and TLDs work →

6. Run or use an exit

The dendritic network is an internal network: by default nothing leaves it for the open internet. An exit is a node that volunteers to do that for others.

Before you run an exit

An exit carries other people's traffic to the internet under your IP address. Abuse complaints, blocklists, and legal or police attention for what passes through it will come to you, as they do for Tor exit operators. Check the law where the machine is and your provider's terms, and prefer a dedicated host to your home connection. An exit also sees where traffic is going, and the content of anything not encrypted end to end.

Run one

"axon": {
  "exit": true,
  "exit_allow_private": false
}

The node publishes the exit as a hidden service and logs its address:

exit: clearnet EXIT (outproxy) serving at <56 characters>.key.axon (AXON) — this node forwards to the open internet

exit_allow_private stays false unless you have a specific reason: it makes the exit refuse private, loopback and link-local destinations, so nobody can use it to reach your own LAN. An exit is a hidden service, so it doesn't need an open port.

Use one

On a client node, name the exit:

"axon": {
  "exit_via": "<exit-address>.key.axon"
}

The node's proxy then sends ordinary internet requests through that exit. Without exit_via, those requests are refused. There is no silent fallback to a direct connection.

7. Storage tuning

KeyDefaultMeaning
capacity_bytes21474836480 (20 GiB)Disk to donate. -capacity-gib sets it.
data_shards6Erasure coding: each object is split into data shards plus parity shards, so any 3 of the default 9 can be lost. Placing an object needs at least data_shards + parity_shards storage holders. On a small test network, lower them (minimum 2 + 1).
parity_shards3
chunk_bytes1048576 (1 MiB)Size of the chunks objects are cut into before coding.
cache_onlyfalseKeep your own content and host nothing for others. Legitimate, but not paid work.
payout_addressemptyWhere earnings go. Required to earn: without it the node logs NO PAYOUT ADDRESS SET and works for free.
drainingfalseRetiring the machine: stop accepting shards and let owners move theirs off.

Earnings come from proof of facilitation: in each hour-long epoch, a node answers audits of what it holds and audits others, and the resulting receipts are settled on chain. Being offline isn't punished; it just isn't paid. Scores are public at rabbiit.io/reputation.

Use the S3 gateway

A storage node gives you a private S3 endpoint at s3_listen (127.0.0.1:9000). Use the access_key and secret_key from your config with any AWS SDK or the AWS CLI:

export AWS_ACCESS_KEY_ID="<access_key from config.json>"
export AWS_SECRET_ACCESS_KEY="<secret_key from config.json>"
export AWS_DEFAULT_REGION=us-east-1      # any value; the node doesn't use it

aws --endpoint-url http://127.0.0.1:9000 s3 mb s3://photos
aws --endpoint-url http://127.0.0.1:9000 s3 cp holiday.jpg s3://photos/
aws --endpoint-url http://127.0.0.1:9000 s3 ls s3://photos/

Keep s3_listen on loopback. A non-loopback S3 address requires tls_cert and tls_key.

8. Advanced roles

These are off by default. Each says what it depends on and how far along it is.

Needs Docker

Container worker (dcs)

Runs other people's Docker containers over AXON, next to your storage node. Set dcs.enabled, dcs.role.worker and dcs.docker_endpoint (default unix:///var/run/docker.sock); optionally a loopback dcs.api_listen. The limits (dcs.limits) are yours to set. Enable it only if you mean to lend CPU and memory to strangers.

Partly wired

Compute (compute)

compute.enabled with offer_cpu and/or offer_gpu. Catalogue CPU work is self-contained. Arbitrary code also needs microvm_kernel and microvm_rootfs, which you supply. Pricing, escrow and settlement are not driven from the node.

Partly wired

Payment channels (channels)

channels.enabled plus peer_listen, api_listen, api_token, key_file, manager, chain_id and rpc. The messaging and mailbox surface runs. On-chain settlement, payout and the watchtower (router.watchtower_enabled) are not driven from the binary today.

Monitor, directive, heartbeat

monitor checks that rabbiit answers from where the node is and publishes the result (targets_url, report_url). network_directive (wallet, sources) is how a node learns the network has moved. heartbeat_endpoint overrides the presence beacon, by default https://rabbiit.io/api/v1/storage/nodes/heartbeat.

The heartbeat goes to rabbiit directly, so rabbiit sees your node's IP. The privacy guarantee is between volunteers; see Security & anonymity.

9. Keep it running

Systemd units ship in packaging/systemd/ in the node's source: dendritic-node.service (the reference unit below), dendritic-node-gateway-home.service for a dedicated gateway, and dendritic-node-update.service + .timer for updates.

/etc/systemd/system/dendritic-node.service

[Unit]
Description=Rabbiit encrypted volunteer storage and edge node
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=rabbiit
Group=rabbiit
ExecStart=/usr/local/bin/dendritic-node -config /var/lib/rabbiit/config.json
Restart=on-failure
RestartSec=5s
TimeoutStopSec=75s

# Only low-port binding is needed. The process does not run as root.
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
NoNewPrivileges=true

PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
LockPersonality=true
MemoryDenyWriteExecute=true
ReadWritePaths=/var/lib/rabbiit

[Install]
WantedBy=multi-user.target

Set it up and start it:

sudo useradd --system --home-dir /var/lib/rabbiit --create-home --shell /usr/sbin/nologin rabbiit
sudo install -m 0755 dendritic-node /usr/local/bin/dendritic-node
sudo install -m 0644 dendritic-node.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now dendritic-node
journalctl -u dendritic-node -f

The first start writes /var/lib/rabbiit/config.json; edit it there and sudo systemctl restart dendritic-node. If you move data_dir, add that path to ReadWritePaths=. Only the node's own directory is writable.

A whole test network on one machine

packaging/dev-cluster/dev-cluster.sh stands up a complete overlay on a single box (relays, services and a hidden-service round trip) with no public relay or coordinator:

make dendritic-node
cp build/dendritic-node packaging/dev-cluster/dendritic-node
cd packaging/dev-cluster
RABBIIT_NODE_BIN=./dendritic-node ./dev-cluster.sh start
RABBIIT_NODE_BIN=./dendritic-node ./dev-cluster.sh test     # expect: {"ok":true,...}

dendritic-dev-cluster.service in the same folder keeps it up under systemd. A dev cluster is not anonymous: it needs allow_same_network and runs on a handful of relays. It proves the overlay works, not that it hides anyone.

10. Example configs

Start the node once so it writes its full config (with your S3 keys and data directory), then merge one of these into it and restart. Each was loaded by the node to check it.

(a) Just browse the network

Host nothing for others, keep the proxy, and keep the dashboard on this machine.

{
  "cache_only": true,
  "ui_listen": "127.0.0.1:9090",
  "axon": {
    "proxy_listen": "127.0.0.1:4480"
  }
}

(b) Donate storage and earn

{
  "capacity_bytes": 107374182400,
  "payout_address": "0xYourWalletAddress",
  "ui_listen": "127.0.0.1:9090"
}

100 GiB. Replace the payout address with your own; a malformed one is refused at startup.

(c) Relay for the network

On a machine with a port the internet can reach (TCP and UDP 4001 here):

{
  "ui_listen": "127.0.0.1:9090",
  "axon": {
    "listen": ["/ip4/0.0.0.0/udp/4001/quic-v1", "/ip4/0.0.0.0/tcp/4001"],
    "announce": ["203.0.113.7:4001"]
  }
}

Use your public IP in announce. The node relays because it has both.

(d) Run an exit

Only after reading the warning.

{
  "cache_only": true,
  "ui_listen": "127.0.0.1:9090",
  "axon": {
    "exit": true,
    "exit_allow_private": false
  }
}

And on a client that should use it:

{
  "axon": {
    "exit_via": "<exit-address>.key.axon"
  }
}