Running the Nyx GUI

The short version

Open Terminal (press Cmd + Space, type "Terminal", hit Enter) and paste:

cd ~/projects/agent-orchestrator
pnpm app

That's it. Two things start together: the moderator (Nyx's brain, a background server) and the desktop GUI (a native window that opens on its own after a moment). Leave the Terminal window open while you use the app — closing it stops Nyx.

First launch is slow. The desktop app compiles native code the first time (a few minutes of scrolling text). Every launch after that is fast. Nothing is wrong, just let it finish.

What you'll see

Terminal prints a Nyx banner, then two colored log streams: mod (cyan, the backend) and gui (magenta, the app).
After the build finishes, the Nyx desktop window opens by itself. Tabs along the side include Deep Research and friends.
To stop everything: click into the Terminal window and press Ctrl + C once.

Other ways to run it

Command	What it starts	When to use
`pnpm app`	Moderator + desktop GUI	The normal way. Use this.
`pnpm app:safe`	Same, with the safer moderator mode	If you want Nyx more locked down
`pnpm desktop`	GUI only (in dev mode, no backend)	UI work only; most features need the moderator
`pnpm dev`	Moderator + web dashboard (no native app)	Browser-based monitoring instead of the desktop app

Setting it up on a new computer

If Nyx isn't on this machine yet, let Claude Code do the whole setup. You need: a GitHub account with collaborator access to the repo (Ethan sends the invite; accept it from your email first), and Claude Code installed.

Open Claude Code in a terminal and paste this prompt:

Clone the private repo github.com/ethanashi/nyx and set it up to run.
Steps: make sure the gh CLI is authenticated (gh auth status; run
gh auth login if not — use my GitHub account, I have collaborator
access). Clone it, then check out the branch
nyx-feat/desktop-app-wave-2. Install whatever is needed: pnpm (via
corepack enable), dependencies (pnpm install), and Rust + Xcode
command line tools if the Tauri desktop app needs them. Then start
the GUI with `pnpm app` and troubleshoot any errors with me until
the Nyx desktop window opens. Read the repo's README/docs if you
need context.

Claude Code will run the commands, watch for errors, and fix them with you. When the Nyx window opens, you're done — from then on it's just pnpm app (see above).

If something complains

Error says	Fix
`command not found: pnpm`	Run `corepack enable` then try again. If that fails: `npm install -g pnpm`
Something about missing packages / `node_modules`	Run `pnpm install` once, then `pnpm app` again
Port already in use	An old copy is still running. Run `Ctrl + C` in any open Terminal tabs, or restart the Mac if unsure
Something about Rust / cargo	Run `xcode-select --install`, and install Rust from rustup.rs (one command, then restart Terminal)

Don't worry about breaking anything. Running the GUI never publishes, deploys, or spends anything. All outward-facing actions in Nyx sit behind approval gates.