Nexus docsOpen Nexus

Install the Nexus Agent

Pair the local agent with your account and install it as a background service with one command, so work runs on your own machine.

The Nexus Agent is a small daemon that runs on your own computer. When it's online, chat turns and skill runs execute locally on your Claude subscription instead of the cloud — your data stays on your machine during the run, and there's no per-token API bill. It also powers the vault sync bridge if you keep local Markdown notes (e.g. an Obsidian vault).

Requirements

  • macOS or Linux. The installer sets up a per-user background service — a launchd LaunchAgent on macOS, a systemd --user unit on Linux. (Windows is on the roadmap.)
  • The Claude Code CLI, installed and signed in to your Claude subscription — the agent executes work through it. The installer warns if it's missing; install it and re-run.

You do not need Node, a checkout of the repo, or any build tools. The installer downloads a prebuilt agent and brings its own Node runtime if your system doesn't already have a recent one.

Install (one command)

  1. In the Nexus web app, open Settings → Tokens & Agents and tap Pair a Nexus Agent.
  2. A short single-use code appears (like L9R4-7J9P). It expires after about ten minutes — generate a fresh one if it lapses.
  3. Copy the whole command shown next to the code and paste it on your Mac or Linux box. It looks like this:
curl -fsSL https://nexus.davidchang.dev/install.sh | bash -s -- --pair L9R4-7J9P --profile you-example-com

Copy it from the app rather than typing this one out: the app fills in your profile name and the --gateway/--download-base flags that point the install at the deployment you copied it from. A pairing code only exists in the environment that issued it, so a command copied from one deployment will not pair against another.

That's it. The installer downloads the agent, ensures a Node runtime, exchanges the code for a scoped agent token (stored in your macOS keychain, or a private file on Linux — you never paste your password into a terminal), installs the background service, and verifies it. When it prints ✓ paired · online, the paired agent also shows Online in Settings within a couple of minutes.

Prefer to read the script before running it?

curl -fsSL https://nexus.davidchang.dev/install.sh -o install.sh
less install.sh
bash install.sh --pair L9R4-7J9P

To upgrade later, just run the one-liner again — it replaces the agent in place and keeps your pairing (no need for a new code).

A second account on the same machine

Got two Nexus accounts — say, personal and work — and want to run both agents on this computer? Install the second one into its own profile. Both run at once: this isn't a toggle, and there's nothing to switch between later.

The install command shown in the app already names a profile after your account (for example you@example.com installs as you-example-com), so a Mac can run several accounts side by side without them colliding. You only pass --profile by hand when installing from a terminal outside the app.

curl -fsSL https://nexus.davidchang.dev/install.sh | bash -s -- --pair NX-YYYY-YYYY --profile work

Pick any short lowercase name for --profile (letters, digits, hyphens). It gets its own token, its own background service, and its own local vault — completely separate from your first install, which stays exactly as it is and needs nothing changed.

See what's installed at any point:

~/.nexus-agent/bin/nexus-agent profiles

This lists every profile on the machine with its space, gateway, and whether the service is running — the fastest way to confirm a pairing landed on the account you meant.

Managing the agent

The background service's name is derived from the profile: dev.davidchang.nexus-agent for your first (default) install, dev.davidchang.nexus-agent.<profile> for a named one. Swap in your profile's name below, or read it straight off nexus-agent profiles.

# is it running? (default profile shown — swap the label for a named one)
launchctl print gui/$(id -u)/dev.davidchang.nexus-agent   # macOS
systemctl --user status dev.davidchang.nexus-agent        # Linux

# restart now
launchctl kickstart -k gui/$(id -u)/dev.davidchang.nexus-agent   # macOS
systemctl --user restart dev.davidchang.nexus-agent              # Linux

# tail the log (a named profile logs to a suffixed sibling file, e.g. nexus-agent.work.log)
tail -f ~/Library/Logs/nexus-agent.log   # macOS
tail -f ~/.nexus-agent/agent.log         # Linux

# uninstall one profile's background service (--profile P for a named one; add --purge to
# also drop its stored token). This never deletes your vault or notes, and never touches
# another profile's install.
~/.nexus-agent/bin/nexus-agent uninstall [--profile P] [--purge]

Removing a profile entirely — service, token, and local metadata, not just stopping it — use remove-profile instead. It prints exactly what it's about to remove and asks you to confirm first (--yes skips the prompt for scripts):

~/.nexus-agent/bin/nexus-agent remove-profile work

This never deletes your notes. It removes the service, the keychain entry, and local metadata (chat history, sync state) only — your vault directory is left exactly where it was. If you genuinely want the vault gone too, add --purge-vault, and even then it only deletes a vault the profile manages itself; if you pointed it at a folder of your own choosing, it refuses and tells you to delete that one by hand.

What the agent does

  • Claims jobs — scheduled skill runs and chat turns route to your agent whenever it's online (presence is measured on a ~2-minute window). If your Mac is asleep, jobs wait visibly and run when it wakes; hosted-capable scheduled jobs can fall back to the cloud runner after a few minutes if you've added an Anthropic key.
  • Runs on your subscription — work executes through the Claude Code CLI under your plan.
  • Syncs your vault — optional two-way mirror between your cloud notes and a local folder, with conflict copies instead of silent merges. See Memory and vault.

The Agent tab shows your paired agents, their presence, what's running right now (with a live log), and a ledger of recent runs with where each one executed.

Un-pairing

Revoke the agent's token in Settings → Tokens & Agents at any time — the daemon's next poll fails and it stops. Re-pair by running the installer again with a fresh code to bring it back. If you're running more than one profile, revoking one account's token only stops that profile's daemon — the other keeps running untouched.

To remove a profile from the machine entirely rather than just un-pairing it, use nexus-agent remove-profile — see Managing the agent above.