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, so 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. It's 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).