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
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:4480and 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 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.
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.
| Flag | What it does |
|---|---|
-config <path> | Use this config file (created if missing). Its directory becomes the data directory unless data_dir says otherwise. |
-config-path | Print where the config file is and exit. |
-show-config | Print 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:
| Variable | What it does |
|---|---|
RABBIIT_EXPERT_LISTEN | Address of the loopback expert API. Default 127.0.0.1:4481. |
RABBIIT_EXPERT_BACKEND | URL of the expert backend that /expert requests are forwarded to. |
RABBIIT_EXPERT_PEERS | Comma-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_mode | What it does | What it needs |
|---|---|---|
storagedefault |
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:
| Role | How you get it | Notes |
|---|---|---|
| Storage node | Default (run_mode: storage) | Stores shards it cannot read and serves the storage DHT. |
| Relay | Automatic once the node has a reachable address: axon.listen + axon.announce | Carries other people's circuits. Opt out with relay_off: true. Stores nothing, learns nothing about what it carries. |
| Exit | Opt-in: axon.exit: true | Forwards requests to the open internet. Read the warning first. |
| Service / expert node | Every node | Hosts 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.
| Key | Default | Meaning |
|---|---|---|
seeds | empty | Relay 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. |
listen | empty | Multiaddrs 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. |
announce | empty | The public ip:port to publish, e.g. 203.0.113.7:4001. With listen, this makes the node a relay. |
relay_off | false | Stay a pure client even with a reachable address. |
relay | false | Force relaying on. Requires listen; the node refuses to start without it. |
proxy_listen | 127.0.0.1:4480 | The loopback HTTP/CONNECT proxy you point a browser at. Loopback addresses only; "" turns it off. |
hops | 3 | Circuit length. 3 is anonymous. 2 is faster and not anonymous. 2–4 allowed. |
allow_same_network | false | Lets a circuit use relays on one network. For dev/test clusters only; see below. |
origin | empty | The 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_contract | off | Name resolution. Section 5. |
exit, exit_allow_private, exit_via | off | Exit 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:
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:
| Key | Meaning |
|---|---|
name_rpc | An Ethereum JSON-RPC URL. Set together with name_contract. |
name_contract | The address of the AxonTLD registry on that chain. |
name_suffixes | Extra 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_fallback | Off 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_contract | true 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.
- 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.comresolves to the AXON identity its registrant set, which says nothing about who ownsexample.comon the internet. .key.axonbypasses the registry. A self-certifying address is dialled directly, whatever the registry says.
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.
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
| Key | Default | Meaning |
|---|---|---|
capacity_bytes | 21474836480 (20 GiB) | Disk to donate. -capacity-gib sets it. |
data_shards | 6 | Erasure 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_shards | 3 | |
chunk_bytes | 1048576 (1 MiB) | Size of the chunks objects are cut into before coding. |
cache_only | false | Keep your own content and host nothing for others. Legitimate, but not paid work. |
payout_address | empty | Where earnings go. Required to earn: without it the node logs NO PAYOUT ADDRESS SET and works for free. |
draining | false | Retiring 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"
}
}