Core

README

Uqda Core 🌐

Uqda (Arabic: عُقَد — nodes/knots) — A fully encrypted, self-organizing IPv6 mesh network. No center. No owner. No single point of failure.

---

📋 Table of Contents

• How It Works
• What Makes Uqda Different
• Get Started
• Connecting to Peers
• Control Your Node
• Installation
• Documentation
• Security
• Contributing
• License

---

🤔 How Does It Work?

Imagine the internet, but without any company controlling it.

In a normal network, your traffic goes through servers owned by corporations. In Uqda, every device is a node — and nodes talk directly to each other.

Normal Internet:          Uqda Network:

You → Company → Friend    You ←——→ Friend
      (they see           (direct, encrypted,
       everything)         no middleman)

Your identity is your key. When you join Uqda, a unique cryptographic key is generated for you. Your IPv6 address is mathematically derived from that key — so your address belongs to you, not to any registrar or ISP.

Your Key → Your Address: 205:xxxx:xxxx:xxxx:...

No one can take it away. No one can reassign it.

---

✨ What Makes Uqda Different?

Feature	Traditional VPN	Uqda
🏢 Central server	Required	Not needed
🔒 Encryption	Usually yes	Always, end-to-end
📍 Your address	Assigned by provider	Derived from your key
🌐 Routing	Through one server	Across all nodes
💀 Single point of failure	Yes	No
💰 Cost	Often paid	Free & open source

🚀 Unique Capabilities

Capability	Why it matters
7 peer transports: TCP, TLS, QUIC, WebSocket, WSS, SOCKS5, UNIX	Works through any network — firewalls, proxies, CDNs, Tor
WSS (WebSocket Secure) peering	Hides mesh traffic as HTTPS — bypasses restrictive networks
SOCKS5 + Tor support	Peer through anonymity networks
Fully decentralized	No coordination server, no lighthouse, no single point of failure
Self-sovereign identity	Your IPv6 address comes from your Ed25519 key — no one can take it
No installation needed	Single binary, no kernel modules, no dependencies
Go embeddable API	Import as a library in your Go applications
8 platforms supported	Linux, macOS, Windows, FreeBSD, OpenBSD, Android, iOS, Docker

---

🚀 Get Started in 3 Steps

1 — Download

Grab the latest release for your platform from the releases page. Each bundle includes both uqda and uqdactl.

2 — Generate your config

./uqda -genconf > uqda.conf

This creates your unique keypair and a ready-to-use config file.

3 — Connect

./uqda -useconffile uqda.conf

Your node is now live. Check your address:

uqdactl getSelf

You'll see something like:

IPv6 address:  205:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
IPv6 subnet:   305:xxxx:xxxx:xxxx::/64
Public key:    abc123...

---

🔗 Connecting to Peers

A peer is any other Uqda node you connect to. The more peers you have, the better your routing across the mesh.

Add peers to your config:

Peers: [
  "tls://some-peer.example.com:12345"
  "quic://another-peer.net:9001"
]

Or add one at runtime without restarting:

uqdactl addPeer uri=tls://some-peer.example.com:12345

Check who you're connected to:

uqdactl getPeers

---

🛠️ Control Your Node

uqdactl is your command-line tool for managing a running node.

Command	What it does
uqdactl getSelf	Your address, key, and routing info
uqdactl getPeers	All connected peers and their stats
uqdactl getTree	The network spanning tree
uqdactl getSessions	Active encrypted sessions
uqdactl addPeer uri=...	Add a peer without restarting
uqdactl removePeer uri=...	Remove a peer
uqdactl list	All available commands

---

📦 Installation

Pre-built packages

Platform	Package
🐧 Debian / Ubuntu	.deb
🪟 Windows	.msi
🍎 macOS	.pkg
🔧 EdgeOS / VyOS	.deb (router)

All packages are published automatically on every release.

Build from source

Requires Go 1.24+

git clone https://github.com/Uqda/Core
cd Core
./build

Produces uqda and uqdactl in the project root.

---

📚 Documentation

Concepts

Guide	Description
About Uqda	How the mesh works, design goals
Configuration	All config options explained
Configuration reference	Quick reference table
Advanced peerings	Tor, multi-homed, priorities
Private two-node network	Closed network between two people
Hosting on Uqda	Run a website inside the mesh
Mesh DNS	Set up DNS for your network
Key rotation	What to do if your key leaks
FAQ	Common questions

Installation guides

Platform	Guide
🐧 Linux	Manual build
🍎 macOS	Manual · .pkg installer
🪟 Windows	Installer
📦 Debian / Ubuntu	Package
📦 Fedora / RHEL	Package
🔧 OpenWrt	Guide
🔧 EdgeOS / VyOS	Guide
😈 FreeBSD	Guide
🐉 Gentoo	Guide

---

🔐 Security Notes

• 🔑 Keep your private key secret — it is your identity on the network
• 🧱 Use a firewall — any node on the mesh can attempt to reach your services
• 🚫 Uqda does not provide anonymity — your peers can see your real IP address
• 🔌 The admin socket has no authentication — never expose it to untrusted networks

---

🤝 Contributing

We welcome contributions! See:

• Contributing Guide — how to get started
• Code of Conduct — community standards
• FEATURES.md — full feature analysis
• Security Policy — reporting vulnerabilities
• Examples — usage patterns

Help us grow: Star the repo, share with friends, and open issues/PRs!

⚖️ License

Licensed under GNU LGPLv3 with a library linking exception. See LICENSE for the full text.