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

---

🚀 Quick Start (1 Minute)

Install

curl -sfL https://raw.githubusercontent.com/Uqda/Core/main/scripts/install.sh | sh

One command — downloads, installs, configures, and starts your node.

Add a peer

sudo uqdactl addPeer uri=tls://jed-peer.ygg.sy.sa:8442

Check your node

sudo uqdactl getSelf

---

🎮 All Commands

Command	What it does	Example
install	Install or update	scripts/uqda-manage.sh install
start	Start the node	scripts/uqda-manage.sh start
stop	Stop the node	scripts/uqda-manage.sh stop
restart	Restart the node	scripts/uqda-manage.sh restart
status	Check everything	scripts/uqda-manage.sh status
info	Show node details	scripts/uqda-manage.sh info
peer add <uri>	Add a peer	scripts/uqda-manage.sh peer add tls://...
peer list	List peers	scripts/uqda-manage.sh peer list
peer remove <uri>	Remove a peer	scripts/uqda-manage.sh peer remove tls://...
logs	View logs	scripts/uqda-manage.sh logs -f
update	Update to latest	scripts/uqda-manage.sh update
uninstall	Remove completely	scripts/uqda-manage.sh uninstall

🖥️ uqdactl Commands

Command	What it does
uqdactl getSelf	Your address, key, uptime, peers
uqdactl summary	Colored node overview
uqdactl stats	Full network statistics
uqdactl getPeers	All connected peers
uqdactl getTree	Network spanning tree
uqdactl getSessions	Active encrypted sessions
uqdactl addPeer uri=...	Add a peer on-the-fly
uqdactl removePeer uri=...	Remove a peer
uqdactl list	All available commands

---

🛠️ 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.