CYBERLUX

Neon storefront. Forty-three onion doors. One build. One app. No dead air.

CyberLux is a layered Next.js fiction stack built for dark-web literacy, classroom demos, mirror discipline drills, and absurdly overbuilt cyberpunk presentation. It runs one app behind Tor + nginx, then fans that app out into dedicated v3 hidden services for the hub, forum, exchange, market, crawler, syndicate, wiki layer, and every other top-level surface in scripts/onion-nodes.json.

This repo is built to feel like a real underground property while still being a controlled demo environment:

• 43 Tor v3 services
• stable loopback range 127.0.0.1:8080–8122
• Next bound only to 127.0.0.1:3000
• one .onion per major surface
• persistent hidden-service identity keyed by HiddenServiceDir
• self-healing backup / restore of onion key directories

What It Does

CyberLux boots a single Next.js app and projects it through multiple onion entry points.

• hub is the main storefront
• forum is Void Aggregate
• exchange is the classifieds stack
• market is the full catalog vertical
• search is Void Crawler
• wiki is the hidden-wiki layer
• w is the syndicate shell network
• dozens of additional dedicated onions map directly to top-level app routes

The routing layer uses host-aware rewrites so a dedicated onion feels like its own property without forking the app into 43 separate deployments.

One-Command Launch

Install system deps first on Debian/Ubuntu:

sudo apt install tor nginx

Then run:

chmod +x start.sh
./start.sh

What ./start.sh does:

1. regenerates Tor / nginx / app route maps from scripts/onion-nodes.json
2. runs git pull --ff-only if the repo has .git (failure is non-fatal)
3. runs npm install
4. repairs .next ownership if a root-owned build left it unwritable
5. runs a production build
6. restores backed-up onion keys if any hidden-service directories are missing
7. installs Tor + nginx config only when it actually changed
8. waits for all onion hostname files, not just the hub
9. refreshes the onion key backup set
10. prints every live .onion URL
11. starts Next on 127.0.0.1:3000

Use Tor Browser and open the printed URLs as:

http://<56-char-v3-address>.onion

Persistent Onion Addresses

Yes: the onion addresses are meant to persist.

Each service uses a fixed Tor directory:

HiddenServiceDir /var/lib/tor/<service-dir>
HiddenServicePort 80 127.0.0.1:<loopback-port>

That means the .onion address remains stable as long as:

• the torDir names in scripts/onion-nodes.json do not change
• /var/lib/tor/<service-dir> is preserved
• or the backup set can restore those directories

Addresses do not rotate on normal app restarts, rebuilds, or standard Tor restarts.

Self-Healing Onion Identity

CyberLux now includes automatic onion key persistence tooling:

• scripts/backup-onion-keys.sh
• scripts/restore-onion-keys.sh

Backup location:

/var/backups/cyberlux-onion-keys/current

Behavior:

• after boot, ready onion service directories are backed up
• on next boot, if a service dir is missing from /var/lib/tor, it is restored from backup
• Tor identity is preserved across ordinary host mistakes, partial deletions, or service-dir drift recovery

This is the difference between “looks cool in a screenshot” and “survives operator error.”

Tor / nginx Topology

Source of truth:

• scripts/onion-nodes.json

Generated artifacts:

• tor/cyberlux-nodes.conf
• nginx/cyberlux-onion-servers.inc
• lib/onionRoutes.generated.ts
• scripts/generated/tor-dirs.txt
• scripts/generated/onion-labels.tsv
• scripts/generated/onion-port-range.txt

Install path:

• /etc/tor/cyberlux-nodes.conf
• /etc/nginx/cyberlux-server-common.inc
• /etc/nginx/cyberlux-onion-servers.inc
• /etc/nginx/sites-available/cyberlux-onion

Runtime:

• Next.js: 127.0.0.1:3000
• nginx onion vhosts: 127.0.0.1:8080–8122
• Tor exposes the public .onion endpoints

Manual Ops

Install or refresh Tor/nginx config:

sudo bash scripts/install-tor-onion.sh

Back up onion keys immediately:

sudo bash scripts/backup-onion-keys.sh

Restore missing onion keys:

sudo bash scripts/restore-onion-keys.sh

Run local-only, skipping Tor/nginx:

CYBERLUX_SKIP_TOR=1 ./start.sh

Start app without the helper:

npm run build
npm run start:onion

Boot At Startup

scripts/cyberlux.service is included as a systemd template for the Next process.

Before installing it, set:

• User=
• Group=
• WorkingDirectory=

Then install:

sudo install -m 0644 scripts/cyberlux.service /etc/systemd/system/cyberlux.service
sudo systemctl daemon-reload
sudo systemctl enable --now cyberlux.service

Notes:

• Tor and nginx should already be installed and enabled
• the service unit keeps the Next process alive
• Tor/nginx config is still managed by the repo scripts

Verification

Run the full local verification suite:

npm run verify

That checks:

• onion config generation
• TypeScript
• shell syntax for boot / install / backup / restore scripts
• full Next production build

Common Failure: .next Permission Hell

If you previously ran a build with sudo, .next may be root-owned and Next will fail with EACCES during unlink / diagnostics writes.

Fix once:

sudo bash scripts/fix-next-perms.sh

Then rerun:

./start.sh

Security Notes

CyberLux is hardened for a demo stack, not sold as magic invisibility.

• Next and nginx bind to loopback only
• Tor exposes the onion endpoints
• do not publish 3000 or 8080–8122 to the public internet
• optional host firewall script: sudo bash scripts/classroom-ufw.sh
• the app can still be insecure if the app code is insecure
• operational mistakes still matter more than branding

Tor hides service reachability better than raw-IP hosting. It does not redeem bad application logic, bad operator habits, or bad judgment.

Site Map

Core verticals:

• / hub storefront
• /market full catalog
• /forum Void Aggregate
• /exchange classifieds
• /barter Ash Pit
• /search Void Crawler
• /hidden-wiki wiki layer
• /darknet-atlas taxonomy / atlas
• /syndicate shell network
• /dashboard personal relay
• /account/hidden-services mirror map

There are additional dedicated onions for many top-level routes beyond those.

Stack

• Next.js 16
• React 19
• Tailwind CSS 4
• nginx
• Tor hidden services
• generated route / host mapping

Final Word

CyberLux is supposed to boot like a machine that knows what it is:

• same onion doors
• same identities
• no shallow mirrors
• no fake “self healing” copy without actual restore logic
• no dead routes pretending to be part of the network

If it starts, it should start hard.