📖 Documentation: dgjones.info/xudanu — user guide, architecture deep-dives, and interactive diagrams. See the Documentation section below for a tour of the interesting parts.
With Docker (seeds a demo corpus of linked lessons, public sandbox):
docker compose -f docker-compose.demo.yml upWith a release binary (no build, no dependencies — downloads here):
./xudanu-server run 127.0.0.1:8080 demo-data --edit-policy public-sandbox --seed-links-demoThen open http://localhost:8080. Create a criticism in one document, link it as a disagreement to a claim in another — and open the claim: your criticism is already there. Nobody edited it. That's what the web never shipped: connections visible from both ends.
No setup at all? Browse the hosted read-only instance: xudanu.com — or break things in the live public sandbox: demo.transclusion.org
Full walkthrough: The 90-Second Bidirectional-Links Demo.
 |
 |
| The Links panel — every connection touching this document, both directions. Click ⇄ to compare any link's ends side by side | Typed links — Comment, Reference, Disagreement, Quotation, See Also, Web — each with its own color in the margin |
 |
 |
| Provenance — who wrote what: per-author attribution with cryptographic signatures | History — the revision timeline; every version remains addressable and comparable |
 |
 |
| Trails — curated reading paths through the docuverse | The editor — writing with visible structure |
The best demo of what Xudanu does: a seeded museum of live link structures — every exhibit is the thing itself, not a picture of it. Click any underlined passage to follow its connection; hover for the type and the far end; watch for the quiet note when you cross in or out of the exhibition.
 |
 |
| The lobby — the floor plan is wired with links: click a room name to walk there | The Spectrum Sentence — one sentence carrying all six link types at once; hover any underline to see the kind and destination |
 |
 |
| The Rebuttal Constellation — the three underlined claims are one gathered end (chips read 1/2/3 of 3), all disputing the same rebuttal | The Live Window — barred passages are transclusions: not copies, but windows onto text that lives in the other document and updates with it |
 |
 |
| The Five-Way Junction — one connection with five named ends, compared side by side | The Two Drafts — the curves are beams: each connects the same passage carried across the two versions, and follows it when either pane scrolls |
Seed it on your own server (from a repo checkout, against a running local server):
npm install ws
XUDANU_ADMIN_PASSPHRASE=<your-admin-pass> node scripts/seed-gallery-unusual.mjs
XUDANU_ADMIN_PASSPHRASE=<your-admin-pass> node scripts/seed-exhibition-gathers.mjsThen open the Gallery — Lobby in the Library, or walk The Curator's Tour in the Trails panel. Seeding against the Docker quickstart (port 8080)? Add SEED_ORIGIN=http://localhost:8080 to the commands. Both seeders are idempotent — re-running is safe.
One binary, one command — and a community has a place to write together: live multi-user editing without locks, published works readable by anyone with no account, and cross-server federation when the conversation outgrows a single machine. The admin console keeps the whole network watchable — live metrics and health checks, session management, and audit logging with authoritative chain verification — the same full cryptographic walk the verify-security-log CLI performs, available in one click. A quick check may warn; only the full walk may say tampering.
 |
 |
| Overview — works, links, sessions, content size, health checks with auto-refresh | Audit — the chained security log, with one-click full verification of every entry, checkpoint, and key rotation |
Try it live — a running server with the interactive Links Course: typed and multi-ended links, gathered end-sets, and live transclusions. Read the documentation — user guides, technical architecture, and visual diagrams. Source on GitHub — releases with static binaries for Linux, macOS, and Windows. Docker image —
ghcr.io/jonesd/xudanu, multi-arch, rebuilt on every release.Start with the Gallery of Unusual Connections — nine rooms of live link structures, seeded on your own server in one command. It is the best tour of what the system does.
xudanu (Xudanu) is a modern Rust and TypeScript implementation inspired by the Xanadu Project and its Udanax Gold (Xanadu 92.1) system.
Disclaimer: Xudanu is an independent, open-source project (Apache 2.0). It is not affiliated with, endorsed by, or sponsored by Ted Nelson, Project Xanadu™, the Xanadu Operating Company, Autodesk Inc., or the Udanax development team. All trademarks belong to their respective owners.
- Visible typed links — Six link types (Comment, Reference, Disagreement, Quotation, See Also, Web) with coloured description boxes and connecting lines
- Real transclusion — Content from one document appears live in another, with provenance tracing back to the source
- Exhibitions — Group related works under a cover: a "Gathers" link from the cover to each member defines the unit. Crossing the boundary is an indication, never a barrier — the reader is told when they enter or leave, and nothing is hidden
- Real-time CRDT collaboration — Multiple users editing the same document without locks
- Transcopyright licensing — Native implementation of Ted Nelson's Transcopyright License (TCo), on by default, alongside a small palette of alternatives (All Rights Reserved, CC-BY, CC-BY-SA, Public Domain). Per-work license metadata with compliance badges and attribution stamping
- Cross-server federation — Documents link across independent servers via BLAKE3-verified tumblers
- Compound document builder — Assemble new documents from passages of existing works
- Image support — Upload, crop, resize, caption persistence, layout mode with inline positioning
- Perspective view — Spatial document landscape showing connected works
Static preview — the image opens the documentation home. On the site itself, this map is live: every region is separately clickable and opens that part's deep-dive.
The full documentation lives at dgjones.info/xudanu. Every region of the map above is clickable there, opening the deep-dive page for that part of the system — or follow the same deep-dives directly from the table below. A few of the interesting parts:
| Deep dive | What you'll find |
|---|---|
| Tumblers & Enfilades | The mathematical foundation under every position, span, and address — why links survive edits: spans migrate because positions are addresses, not offsets |
| The Transclusion Engine | Canopy trees, backfollow queries, and live content reuse — the structural heart of Xanadu |
| Transclusion Architecture | How our range-based transclusion works, and how it compares to Gold's enfilade/I-stream model |
| Provenance & Attribution | "Who wrote this?" answered at the character level — Ed25519 span signing, tamper-evident logs, W3C PROV export |
| Ent, DagWood & Trace DAG | The versioning spine adapted from Udanax Gold: partial-order branches that preserve conflicts instead of resolving them away |
| The Xanadu Network Guide | Two independent servers sharing content via tumblers — verified working, with BLAKE3 checks and automatic backlinks |
| What People Said Killed Project Xanadu | The four standard objections to the 1960 design, answered by a running xanalogical system |
| From Udanax to Xudanu | The algorithms, the people, and the 35-year path from Nelson's vision to running Rust |
| Wire Protocol | The complete 140+ operation WebSocket API — the integration surface for building your own client. Declared a compatibility contract: within api_version 1, changes are additive-only and the op table is CI-pinned |
Also worth knowing: the User Guide, the Technical Architecture deep-dive (Big-O analysis of every data structure), and the Gold Heritage concept map tracing every Udanax-Gold concept to its Rust descendant.
The canonical name of the project is xudanu (lowercase).
- Used for: code, crates, CLI tools, and repository naming
- Example:
use xudanu::...,xudanu serve
The capitalized form “Xudanu” may be used in prose or discussion when referring to the system more generally.
The original Xanadu work introduced a deeply innovative model for structured documents, versioning, and linking. xudanu continues that lineage by:
- Translating core ideas into Rust
- Supporting WebAssembly (WASM) execution
- Refining and optimizing core data structures and algorithms
- Making the system usable in modern environments (web, services, distributed systems)
This is not just a port—it is an evolution of those ideas.
xudanu builds on a long lineage of research and engineering:
Xanadu Project (1960s–1990s)
↓
Xanadu 92.1 (Udanax Gold)
↓
xudanu (Rust / WebAssembly)
The original Xanadu system explored new models for hypertext, identity, and structure that remain relevant today.
The Udanax Gold source code was released open-source on August 23, 1999 under the MIT/X11 license. See udanax.xanadu.com for the original announcement, license, and supporting documents.
The Xanadu project, initiated in the 1980s, explored a radically different approach to hypertext and information systems. Its implementation, Xanadu 92.1 (later released as Udanax Gold), introduced novel data structures and models.
xudanu is a modern reimplementation and evolution of those ideas.
This project:
- Translates and adapts concepts from Udanax Gold into Rust
- Introduces optimizations and architectural changes
- Targets modern execution environments including WebAssembly
We aim to preserve the strengths of the original system while making it usable in today’s ecosystem.
xudanu exists to continue and extend ideas that were ahead of their time.
By combining those foundational concepts with modern tools such as Rust and WebAssembly, we aim to:
- Improve safety and performance
- Enable new applications
- Support experimentation and real-world deployment
This project is an ongoing evolution, not a static port.
Developer Preview — the system is functional and tested (4,300+ tests passing) but APIs and data formats may evolve. Snapshot migration ensures your data survives upgrades. Versioned wire protocol supports backward-compatible API changes.
Feature Status — comprehensive tracking of all Xanadu, Udanax Gold, and Xudanu features with implementation status. Covers Nelson's 17 Rules, core data structures, wire protocol, frontend, security, federation, and Xudanu-exclusive additions (LLM integration, cryptographic provenance, CRDT collaborative editing).
The common scenarios, in the order people actually hit them.
Before you start (all scenarios):
- Docker running — check with
docker infoin a terminal. If it hangs or errors, start Docker Desktop (macOS/Windows) or thedockerservice (Linux). Ifdocker infohangs for more than ~10 seconds, the daemon is unresponsive: quit Docker Desktop completely and relaunch it. - Port 8080 free — check with
lsof -i :8080(macOS/Linux) ornetstat -an | findstr 8080(Windows). If something else is listening, stop it or change the port mapping in the compose file (left side of"8080:8080"). - That's it — no database, no API keys, no configuration files.
curl -O https://raw.githubusercontent.com/jonesd/xudanu/main/docker-compose.single.yml
docker compose -f docker-compose.single.yml up -dOpen http://localhost:8080. Create a document, select some text,
make a link. Data persists in a named volume — docker compose -f docker-compose.single.yml down to stop (-v also deletes the data).
Then seed the Gallery of Unusual Connections — nine rooms of live link structures, the fastest way to see what links, gathered ends, and transclusions actually look like.
No Docker? Grab a static binary from releases — Linux (musl) or macOS (Apple Silicon + Intel) — and:
./xudanu-server run 127.0.0.1:8080 ./dataSame single-node setup as Scenario 1, run on your VPS/home server behind HTTPS. Point the compose at a persistent directory, put your domain in front with any reverse proxy (Caddy example):
yourdomain.com {
reverse_proxy localhost:8080
}
Your notes, your machine, no cloud. Works offline; federation is opt-in and off by default.
Where your data lives. The compose stores everything in a named
Docker volume (xudanu-data) — on your disk, in documents/links/
chunks/revisions/provenance. Nothing leaves the machine.
If you prefer a visible directory (rsync-able, easy to inspect), swap the volume line in the compose for a bind mount:
volumes:
- ./xudanu-data:/dataBackup (works for either storage style):
docker run --rm -v xu-gold-2026_xudanu-data:/data \
-v $(pwd):/backup alpine tar czf /backup/xudanu-data.tar.gz /dataUpdate to the latest image — your data is untouched:
docker compose -f docker-compose.single.yml pull
docker compose -f docker-compose.single.yml up -dStill one server — Xudanu is multi-user by design. Share the URL;
people create identities, write simultaneously (CRDT-based live
editing), and every passage carries its author's signed provenance.
Set --edit-policy public-sandbox for a wiki-style instance, or
keep the default owner-only policy with per-work permissions.
Identities are created in-app by default — a name and a password, no email, no external accounts. If you want externally accountable sign-in instead, enable GitHub and/or Google OAuth per provider by setting environment variables on the server:
XUDANU_GITHUB_CLIENT_ID=... # GitHub → Settings → Developer settings → OAuth Apps
XUDANU_GITHUB_CLIENT_SECRET=...
XUDANU_GOOGLE_CLIENT_ID=... # Google Cloud console → Auth Platform → Clients
XUDANU_GOOGLE_CLIENT_SECRET=...
The app detects what your server has configured and shows exactly those buttons on the sign-in panel; the local identity path always remains. Callback URLs and the full walkthrough: Terms for operators — identity models.
The app works on phones (editing included) and installs as a PWA — Share → Add to Home Screen — running standalone with an offline reading cache. Android support is on the roadmap.
Three servers on one machine to see the network features — search across servers, pull a passage by reference from another node, watch it update when the source edits:
git clone https://github.com/jonesd/xudanu.git && cd xudanu
docker compose -f docker/docker-compose.yml up --build -d
# Node 1: http://localhost:8081 · Node 2: :8082 · Node 3: :8083Real multi-server deployments use the same image on separate
machines with --peer <address> and --trusted-peer-key <key> —
see the network guide.
git clone https://github.com/jonesd/xudanu.git && cd xudanu
cargo build --features server -p xudanu
# In-memory (no persistence):
./target/debug/xudanu-server run 127.0.0.1:8080
# With persistent storage:
./target/debug/xudanu-server init ./data
./target/debug/xudanu-server run 127.0.0.1:8080 ./dataThe Docker image (ghcr.io/jonesd/xudanu, multi-arch amd64+arm64)
is rebuilt every release: latest, stable, 1.7, edge (main).
If you downloaded a pre-built binary and see "Apple could not verify xudanu-server":
xattr -cr /path/to/xudanu-serverOr right-click the binary → Open → click Open again in the dialog.
Go to http://127.0.0.1:8080 — you'll see the document editor.
Everything above works without any AI components. LLM features are entirely opt-in: document summarization, writing feedback, title suggestions, and auto-tagging. When enabled, they use a local LLM via Ollama — no API keys, no cloud accounts, no data leaves your machine. If Ollama isn't running, Xudanu simply disables these features; the core system is unaffected.
Install Ollama:
# macOS
brew install ollama
ollama serve &
# Linux
curl -fsSL https://ollama.ai/install.sh | shPull a model:
# Small and fast (recommended for testing):
ollama pull qwen2.5:1.5b
# Larger, better quality:
ollama pull qwen2.5:7b
# or
ollama pull llama3.1:8bStart the server with LLM enabled:
OLLAMA_BASE_URL=http://localhost:11434 \
OLLAMA_MODEL=qwen2.5:1.5b \
./target/debug/xudanu-server run 127.0.0.1:8080 data \
--allowed-origin http://localhost:5173 \
--csrf-tokenOr use the included script:
cd original-code/xanadugold/src-rust
./scripts/start-llm.shOnce enabled, open any document and you'll see gold sparkle buttons in the format bar:
| Feature | Description |
|---|---|
| Summarize | Describes what changed between document versions |
| Feedback | AI writing coach — clarity, structure, persuasiveness |
| Title | Generates a title from document content |
| Auto-Tag | Suggests concept tags, creates links to existing concepts |
LLM-authored text is tagged with gold/amber attribution in the provenance panel.
- The Twelve Problems — how Udanax Gold solved hypertext's hard parts (enfilades, crums, tumblers, displacements), with diagrams and where Xudanu extends each; the Coles Notes are the condensed version.
- Technical Architecture — a detailed walkthrough of the core data structures, algorithms, and performance characteristics (O-trees, GrandMap, Canopy pruning, H-trees, transclusion queries, DagWood concurrent edits). Recommended for all developers and architects.
- Xudanu in One Page — a concise overview of the entire system.
- 30 Years of Hypertext Innovation — historical context connecting Xanadu to modern hypertext.
- Storage System — content-addressed chunk store and manifest design.
- Notification System — content watch, similarity matching, and micropayments.
- All documentation — index of all available docs.
- Server README — CLI reference, web UI guide, TLS setup, federation, and architecture details.
Xudanu runs as a single server on a laptop, but it also supports multi-machine federation — a cluster of independent peer nodes that replicate content, converge membership, and make cluster-wide decisions via PBFT consensus.
What works today (v0.8.1):
- Outbound dialer with automatic reconnect (exponential backoff)
- Mutual Ed25519/X25519 handshake with ChaCha20-Poly1305 encrypted channels
- Content replication (BLAKE3-verified, CRDT-convergent — duplicates are harmless)
- Membership convergence via web-of-trust endorsements
- PBFT governance broadcast for cluster-wide decisions
- Self-healing: a partitioned or crashed node catches up automatically on return
Try it with Docker (3-node cluster):
docker compose up --build
# Peer A: http://localhost:8081
# Peer B: http://localhost:8082
# Peer C: http://localhost:8083Each peer is a full node (web UI + client WS + federation WS). Upload a document on one peer — it appears on the others within seconds.
Manual two-node setup:
# Peer A — logs its verifying key at startup
xudanu-server run 127.0.0.1:8081 data-a \
--peer 127.0.0.1:8082 \
--trusted-peer-key <B's verifying key>
# Peer B — registers A's key
xudanu-server run 127.0.0.1:8082 data-b \
--peer 127.0.0.1:8081 \
--trusted-peer-key <A's verifying key>Scaling: 3-10 peers on VPS or donated machines works out of the box (full-mesh replication). Beyond 20 nodes, incremental sync and gossip relay are on the roadmap.
Full guide: Federation Activation — PBFT explained, broadcast/sync diagrams, chunk replication flow, failure recovery scenarios, scaling estimates, and a problem checklist by cluster size.
Documentation is served at dgjones.info/xudanu/ via GitHub Pages.
- Workflow:
.github/workflows/deploy-docs.yml - Trigger: Any push to
mainthat changes files indocs/** - Source: The entire
docs/directory is uploaded as the Pages artifact - No build step — static HTML/Markdown served as-is
To add or update documentation:
- Add/edit files in
docs/(HTML files match the dark theme; Markdown files indocs/dev/) - If adding a new page, link it from
docs/index.html - Commit and push to
main— GitHub Actions deploys automatically
xudanu is licensed under the Apache License 2.0.
The bundled web fonts (Orbitron, Inter, JetBrains Mono, Source Serif 4) are
redistributed under the SIL Open Font License 1.1 — see
web/app/public/THIRD-PARTY-NOTICES.md,
which ships with every distribution.
Portions of this project are derived from Udanax Gold (Xanadu 92.1), which was released under the Xanadu X11 license (a permissive license similar to MIT).
The original license is included in:
original-code/xanadugold/LICENSE-udanax-gold.txt
Both licenses are permissive.
This means you may:
- Use this software commercially
- Modify and distribute it
- Integrate it into proprietary systems
Requirements:
- Preserve license notices
- Include attribution to the original Xanadu/Udanax work
Xudanu is an independent, open-source project. It is not affiliated with, endorsed by, or sponsored by Ted Nelson, Project Xanadu™, the Xanadu Operating Company, Autodesk Inc., or the Udanax development team. Xudanu implements concepts from the open-sourced Udanax-Gold codebase (released 1999 under the Xanadu X11 license) using original code. "Xanadu" is a project name of Ted Nelson. All trademarks belong to their respective owners.
Contributions are welcome.
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
We acknowledge the original Xanadu vision and the engineers who built Udanax Gold. Their work continues to influence how we think about information systems today.