/ home-hosting guide Jump to checklist

Self-hosted orchestration

Host Nyx at Home

A concrete guide to running 4 moderators and up to 32 concurrent workers on a machine at your house, accessible 24/7 by 2 people from anywhere. Includes hardware recommendations at three budget bands, remote-access setup, and everything needed to keep it running unattended.

The surprising part

You do not need a GPU, VRAM, or a workstation-class CPU. Nyx workers and moderators are orchestration processes: Node/tsx programs that edit files, run git and tests, and stream tool calls to Claude running in Anthropic's cloud over the API. The heavy inference happens on Anthropic's hardware, not yours. What you actually need is RAM (many concurrent Node processes), core count (concurrency), and fast NVMe storage (git worktrees and node_modules stacks). A quiet, efficient mini PC or Mac Mini is the right buy. A gaming tower would be wasteful and loud for this workload.

Section 02

How Nyx Uses Your Hardware

Cloud inference, local orchestration

When a Nyx worker runs a task, it spawns a claude or claude-code process that opens an HTTPS stream to api.anthropic.com. The LLM is entirely remote. Your home box sees nothing heavier than JSON tool-call payloads arriving over a network connection. Each moderator is a Hono HTTP server (Node/tsx) gating those calls and managing the queue.

The bottleneck on your machine is memory footprint (each worker process keeps a Node heap alive for the duration of its task, plus subprocesses for git, vitest, tsc, npm), concurrent I/O (file edits, git operations, shell commands), and NVMe throughput (git worktree checkouts, node_modules symlinks).

4 moderator procs (Hono :8787)
32 worker procs (Node/tsx)
~64-128 short-lived subprocesses (git, tsc, vitest...)
1 OS + browser for the web UI
0 local GPU jobs

Capacity sizing at 4 moderators + 32 workers

Resource Per-process estimate Full-fleet total Overhead Working set Verdict
RAM (workers) 250-500 MB 32 x 0.4 GB = ~13 GB peak: npm install spikes 13 GB
RAM (moderators) 300-600 MB 4 x 0.5 GB = ~2 GB 2 GB
RAM (OS + browser) 4-6 GB macOS/Linux + browser: +1-2 GB base overhead 6 GB
RAM total ~21 GB working set spikes higher during builds 32 GB floor
CPU cores I/O-bound, not compute-bound 8 perf-cores floor concurrent spawning 12-16 cores ideal any modern 8+ core
Disk worktree ~1-4 GB 32 worktrees + node_modules: 30-80 GB/project per active project 512 GB min 1 TB recommended
Network API streaming: ~50-200 KB/s per worker 32 workers: ~6 MB/s peak latency to Anthropic matters Gigabit Ethernet wired, not Wi-Fi
Power (24/7) Mac Mini idle: 5-10 W peak: 30-50 W (Mac Mini) / 15-65 W (mini PC) vs gaming rig: 300-600 W trivial cost quiet + cheap to run
16 GB: too tight (fits ~12-16 workers comfortably)
24 GB: usable (~22-26 workers; pressure during heavy builds)
32 GB: comfortable floor (all 32 workers; ~11 GB headroom)
64 GB: real headroom (32 workers + parallel builds + browser automation)

These estimates assume a moderately busy queue. When workers run npm installs, compile TypeScript, or run vitest in parallel, resident memory and disk I/O spike. 64 GB gives enough slack that you never have to think about it. 32 GB requires a little discipline (avoid stacking 6 npm-heavy workers simultaneously). 16 GB means actively managing concurrency and accepting fewer simultaneous workers.

Section 03

What to Buy

Three budget bands, each with two archetypes. Archetype A (Mac Mini): best efficiency, quietest, macOS parity with how Nyx is developed today. Archetype B (AMD mini PC): more RAM and storage per dollar, runs Linux, more cores for the money. Prices verified June 2026.

$600-900 Entry band

Archetype A / macOS

Apple Mac Mini M4

$799

  • CPUM4, 10-core CPU, 10-core GPU
  • RAM16 GB unified
  • Storage512 GB NVMe
  • Power (idle/peak)~7 W / ~30 W
  • EthernetGigabit built-in
12-16 of 32 workers

16 GB is below the 32 GB comfortable floor. You can run Nyx, but concurrency is limited: expect to cap workers around 14-16 and avoid running heavy npm installs in parallel. Quiet, fanless, and draws less than a light bulb. The 256 GB model was discontinued in May 2026; the base now ships at 512 GB.

Good if you need silence and macOS parity and can live with ~half the worker capacity.

Archetype B / Linux

Beelink SER8 (Ryzen 7 8845HS)

~$699-750

  • CPURyzen 7 8845HS, 8C/16T, up to 5.1 GHz
  • RAM32 GB DDR5
  • Storage1 TB PCIe 4.0 NVMe
  • Power (idle/peak)~15 W / ~65 W
  • Ethernet2.5 Gigabit built-in
All 32 workers

Hits the 32 GB comfortable floor at a lower price than the Mac Mini. 1 TB gives real room for worktree stacks. Runs Ubuntu or Debian; setup takes an extra hour versus macOS parity. The 8845HS is a strong mobile CPU with good per-core performance and handles 16 concurrent threads without thermal throttling in a 24/7 chassis.

Best value for all 32 workers now. If the Linux setup overhead is acceptable, this is the pick.
$1,000-1,200 Sweet spot BEST VALUE BAND

Archetype A / macOS

Apple Mac Mini M4 (24 GB)

$999

  • CPUM4, 10-core CPU, 10-core GPU
  • RAM24 GB unified
  • Storage512 GB NVMe
  • Power (idle/peak)~7 W / ~30 W
  • EthernetGigabit built-in
22-26 of 32 workers

24 GB is meaningfully better than 16 GB but sits between the 32 GB floor and the 64 GB comfortable target. Handles a full moderator fleet plus ~24 workers. Quiet, macOS parity, same M4 chip. Storage is 512 GB, which is fine for one or two active projects but will fill with three or more running simultaneously.

Good macOS option if you plan to scale concurrency gradually and prioritize silence.

Archetype B / Linux

Minisforum UM890 Pro (64 GB)

~$999-1,099

  • CPURyzen 9 8945HS, 8C/16T, up to 5.2 GHz
  • RAM64 GB DDR5
  • Storage1 TB PCIe 4.0 NVMe
  • Power (idle/peak)~18 W / ~65 W
  • Ethernet2x 2.5 Gigabit built-in
All 32 workers + real headroom

64 GB handles the full fleet with ~43 GB of headroom after the ~21 GB working set. That slack absorbs parallel npm installs, full vitest runs across worktrees, and a browser for the web UI simultaneously. The Ryzen 9 8945HS is stronger than the 8845HS on sustained multi-core. The Minisforum official store typically prices this lower than retail; Amazon prices land around $999-1,099. Check both before buying.

The sweet-spot pick. Handles 4 mods + 32 workers with enough slack to never think about memory.
$1,300-1,600 Long-term comfort

Archetype A / macOS

Apple Mac Mini M4 Pro

$1,399

  • CPUM4 Pro, 12-core CPU, 16-core GPU
  • RAM24 GB unified
  • Storage512 GB NVMe
  • Power (idle/peak)~7 W / ~50 W
  • Ethernet10 Gigabit Ethernet
22-28 of 32 workers

The M4 Pro chip is substantially faster on sustained CPU workloads: 12 performance cores handle concurrent TypeScript compilation, vitest runs, and git operations significantly faster than the base M4. 24 GB is still the same RAM ceiling, but the faster I/O and 10 Gigabit Ethernet port make a difference for a 24/7 server role. Best long-term efficiency and build speed per watt. Matches your current darwin development environment exactly: no environment delta.

Best choice for longevity and macOS parity. Recommended if you want the machine to last 5+ years.

Archetype B / Linux

GEEKOM AE8 / Minisforum UM890 Pro (64-96 GB)

$1,200-1,499

  • CPURyzen 9 8945HS, 8C/16T
  • RAM64-96 GB DDR5
  • Storage1-2 TB PCIe 4.0 NVMe
  • Power (idle/peak)~18 W / ~65 W
  • Ethernet2x 2.5 Gigabit built-in
32 workers + multiple browser sessions

96 GB is genuine overkill for the current target, but it future-proofs against scaling to 48-64 workers or running heavy browser automation suites alongside the queue. The GEEKOM AE8 base ships at 32 GB; confirm 64 GB configuration availability before ordering. This band buys comfort and growth room, not necessity.

Maximum headroom option. The Mac Mini M4 Pro is the better 24/7 pick unless you plan to grow well past 32 workers.

Ethernet matters. Plug the box into your router with a cable. Wi-Fi introduces variable latency on the API stream and occasional drops that strand in-flight workers. The keep-alive script handles reconnection, but wired is simpler and faster.

Section 04

24/7 Operation

The queue is in SQLite on disk. A crash mid-write can corrupt it. A mis-configured sleep setting kills workers silently. Getting these five things right means the machine runs unattended indefinitely.

Auto-start on boot

On macOS, use a launchd plist to launch the moderator at login or at boot. On Linux, use a systemd unit with Restart=always.

# ~/Library/LaunchAgents/com.nyx.moderator.plist (excerpt) <key>ProgramArguments</key> <array> <string>/bin/bash</string> <string>scripts/keep-moderator-alive.sh</string> </array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/>
# /etc/systemd/system/nyx-moderator.service (excerpt) [Service] WorkingDirectory=/home/user/projects/agent-orchestrator ExecStart=/bin/bash scripts/keep-moderator-alive.sh Restart=always RestartSec=5

Crash recovery

The repo's scripts/keep-moderator-alive.sh script is a purpose-built supervisor: it polls /health every 5 seconds, kills and restarts the moderator if it goes non-200, and includes two independent recovery triggers for workers stranded by an outage:

  • Sleep/wake heuristic: if more than 60 s pass between 5-second ticks, the host woke from sleep; it POSTs to /control/resume-orphans
  • Network watcher: a background subprocess polls 1.1.1.1 every 15 s; a down-to-up transition also fires resume-orphans (catches Wi-Fi drops that don't involve sleep)

Disable sleep

The machine must not sleep while workers are active. A sleeping host disconnects API streams and leaves workers stranded.

# macOS: disable display + system sleep sudo pmset -a sleep 0 sudo pmset -a disksleep 0 # Or: System Settings > Energy Saver > Prevent sleep
# Linux systemd: prevent suspend/hibernate sudo systemctl mask sleep.target suspend.target \ hibernate.target hybrid-sleep.target

UPS (power blip protection)

SQLite writes are atomic, but a hard power cut mid-write can leave the queue database in an inconsistent state. A small UPS (APC BE600M1 or similar, ~$60-80) gives the moderator time to finish the current write and shut down cleanly. This is the single cheapest reliability upgrade you can make.

Pair the UPS with a USB or network connection to the host so it can trigger a graceful shutdown before the battery runs out.

Monitoring

Two things to watch: is the moderator answering, and is the queue draining?

# Cron every 5 min: alert if moderator is down curl -sf http://localhost:8787/health \ || echo "Moderator down at $(date)" \ | mail -s "nyx alert" you@example.com

For remote visibility, expose /health and the web UI via the Cloudflare Tunnel described in the next section, then check from any browser.

Log rotation

The keep-alive script logs to /tmp/keep-moderator.log and /tmp/moderator.log. Workers write transcripts to disk. Without rotation these fill the disk over weeks.

# /etc/logrotate.d/nyx /tmp/keep-moderator.log { daily rotate 7 compress missingok notifempty }

On macOS, use newsyslog or a simple daily cron that truncates logs older than 7 days.

Section 05

Reaching Nyx from Anywhere

Two complementary layers: the terminal/TUI path and the browser/web-UI path. You need both; they use different tools because the use cases are different. Note: this guide itself is a static file hosted on Cloudflare Pages. The live moderator UI is a separate runtime service reached via the methods below.

nyx TUI: Tailscale + SSH + tmux Tailscale

Tailscale creates a private WireGuard network between your devices. Every device gets a stable private address (e.g. 100.x.y.z or a MagicDNS name). No port forwarding on your router, no public exposure of the SSH port. Both people install Tailscale on their laptops and phones and join the same tailnet.

  1. Install Tailscale on the home box: curl -fsSL https://tailscale.com/install.sh | sh then sudo tailscale up (one-time login; Tailscale is not yet installed on your host).
  2. Install Tailscale on each person's laptop and phone; log in with the same account or an organization you share.
  3. Confirm connectivity: tailscale ping <hostname> from your laptop.
  4. Enable SSH on the home box (macOS: System Settings > General > Sharing > Remote Login).
  5. Start a persistent tmux session on the home box: tmux new -s nyx. Run the nyx TUI inside it.
  6. Connect from anywhere: ssh user@<tailscale-hostname> then tmux attach -t nyx.
  7. For a second person: use a separate tmux session (tmux new -s nyx-2) or share the same session read-only.

Tailscale not yet installed on the host. Install it before anything else in the remote-access setup.

Moderator web UI: Cloudflare Tunnel + Access Cloudflare

Cloudflare Tunnel (cloudflared) creates an outbound-only connection from your home box to Cloudflare's edge. Zero open inbound ports on your router. Pair it with Cloudflare Access (free tier) to gate the URL to the two allowed email addresses. The result: a clean public HTTPS URL like nyx.yourdomain.com accessible from any browser, login-protected, with no VPN required.

  1. Install cloudflared on the home box: brew install cloudflared (macOS) or the Linux package.
  2. Authenticate: cloudflared tunnel login (opens a browser for Cloudflare account auth).
  3. Create a tunnel: cloudflared tunnel create nyx-moderator.
  4. Add a config: route https://nyx.yourdomain.com to http://localhost:8787 in the tunnel config file.
  5. Run as a service: cloudflared service install so the tunnel starts on boot.
  6. In the Cloudflare Zero Trust dashboard, create an Access Application for nyx.yourdomain.com; add both email addresses as allowed users.
  7. Visit https://nyx.yourdomain.com from any device. Cloudflare prompts for email OTP; approved emails get through.

Use Tailscale for SSH + TUI (simpler, lower latency for terminal work). Use Cloudflare Tunnel for the browser UI (shareable HTTPS URL, no VPN app required on the viewer's device).

Section 06

Quickstart Checklist

From unboxed machine to first worker running. Steps are ordered; complete each before the next.

Phase 1: Hardware setup

  1. Unbox the machine. Plug in power, Gigabit Ethernet (to router, not Wi-Fi), and a monitor/keyboard for initial setup only.
  2. Disable sleep. macOS: System Settings > Battery/Energy Saver > set sleep to Never. Linux: systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
  3. Plug the machine into a UPS. Confirm the UPS is charged and the OS recognizes it.
  4. Set a static IP or DHCP reservation on your router so the machine's address never changes.

    5. Phase 2: OS and core tools

  5. macOS: install Xcode Command Line Tools (xcode-select --install). Linux: sudo apt update && sudo apt install -y build-essential git curl
  6. Install Node.js (LTS, 20+) and pnpm: npm install -g pnpm
  7. Install Claude Code: follow the official install instructions from Anthropic.
  8. Configure your ANTHROPIC_API_KEY in the shell profile (~/.zshrc or ~/.bashrc).

    9. Phase 3: Clone and bootstrap Nyx

  9. Clone the orchestrator repo: git clone <your-repo-url> ~/projects/agent-orchestrator
  10. Install dependencies: cd ~/projects/agent-orchestrator && pnpm install
  11. Run the database migrations (if any): check the repo README for the migration command.
  12. Test a single moderator start: pnpm --filter @orchestrator/moderator dev:safe -- confirm it answers on http://localhost:8787/health

    13. Phase 4: Remote access

  13. Install Tailscale on the home box: curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up. Complete the browser login.
  14. Enable SSH on the home box. Test from your laptop: ssh user@<tailscale-hostname>
  15. Start a persistent tmux session: tmux new-session -d -s nyx
  16. Install Tailscale on your laptop and phone. Confirm tailscale ping <home-hostname> succeeds.
  17. Install and configure cloudflared. Set up the Cloudflare Tunnel to route your domain to localhost:8787. Install it as a system service.
  18. In Cloudflare Zero Trust, create an Access Application for the moderator URL. Add both email addresses as allowed users.
  19. Test the browser UI from your laptop over Cloudflare Access. Confirm login works for both people.

    20. Phase 5: Auto-start and monitoring

  20. macOS: install the launchd plist for scripts/keep-moderator-alive.sh. Linux: install the systemd unit. Load and start it.
  21. Reboot the machine. Confirm the moderator comes up automatically and /health returns 200 within 30 seconds of boot.
  22. Add a cron health-check alert so you get notified if the moderator goes silent.
  23. Configure logrotate (or equivalent) for /tmp/keep-moderator.log and /tmp/moderator.log.

    24. Phase 6: First worker

  24. SSH into the home box via Tailscale. Attach to tmux: tmux attach -t nyx
  25. Launch the nyx TUI. Queue a small test task.
  26. Confirm a worker picks it up and completes it. Check the web UI from your browser via the Cloudflare Access URL.
  27. You are done. Disconnect from tmux (Ctrl-B D). The machine runs on its own.