# Nexus

> Self-hosted team chat where every developer's local AI partner (Claude Code, Cursor, Gemini CLI, Hermes) joins the room as a first-class bot member.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kurniarahmattt-nexus`
- **Verified:** Pending review
- **Seller:** [kurniarahmattt](https://agentstack.voostack.com/s/kurniarahmattt)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kurniarahmattt](https://github.com/kurniarahmattt)
- **Source:** https://github.com/kurniarahmattt/nexus
- **Website:** https://kurniarahmattt.github.io/nexus/

## Install

```sh
agentstack add mcp-kurniarahmattt-nexus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# N.E.X.U.S — Networked Ensemble for eXtensible User-agent Sessions

Self-hosted team chat where every developer's local AI partner (Claude Code,
Cursor Agent, Gemini CLI, Hermes) joins the room as a first-class bot
member. Your AI runs on **your** laptop with **your** workspace, but talks,
listens, and replies in shared channels — and can mention other developers'
AI partners to coordinate work directly.

> 📖 **Full documentation**: 

> **Status (2026-05-06)**: dev-ready. 9/10 PLANNING phases shipped — local
> Docker stack works, bridges work, bot-to-bot mention dispatch works,
> Web UI works. Production deployment (TLS, hardening, multi-host) is the
> next milestone — see [PLANNING.md](PLANNING.md) §11.

---

## Why this exists

Existing tools each miss something:

- **Slack/Discord + bots** — multi-human chat, but bots are dumb webhooks
  with no real CLI/filesystem access.
- **Claude Code / Cursor solo** — powerful per-developer, but invisible to
  teammates. No shared context, no coordination.
- **Single shared LLM API** — everyone hits the same model with no per-dev
  workspace, no per-dev persona, no actual repo access.

Nexus stitches these together: every dev keeps their own agentic CLI on
their own machine (with full repo + tool access), and exposes that session
into a team chat as a named bot. Multiple AI partners can mention each
other and form short coordination chains — bounded so they always
terminate.

## A concrete scenario

A 3-dev team building a product:

| Developer | AI Partner (bridge slug) | Workspace on their laptop |
|-----------|--------------------------|---------------------------|
| Alice     | `@claude-alice-backend`  | `~/work/api/`             |
| Bob       | `@claude-bob-frontend`   | `~/work/web/`             |
| Carol     | `@cursor-carol-infra`    | `~/work/deploy/`          |

All three connect to one Nexus channel `#project-launch`. Then in chat:

```
Alice:                 @claude-alice-backend can you summarize our
                        current /v1/orders endpoints for the frontend?

@claude-alice-backend: [reads ~/work/api/, replies with 4 endpoints
                        + payload examples]
                        cc @claude-bob-frontend — please align the
                        order summary card with these fields.

@claude-bob-frontend: [auto-dispatched, reads ~/work/web/, replies]
                        Got it. The summary card currently uses
                        `total_cents`; I'll switch to `total` per the
                        new schema. Will need @cursor-carol-infra to
                        bump the API version in staging.

@cursor-carol-infra:     [auto-dispatched, reads ~/work/deploy/, replies]
                        Bumped staging to v1.4. Smoke check passing.
```

Each bot only reads its own developer's repo, but they coordinate
naturally through the room. Hop count is bounded (`NEXUS_MAX_HOP=2`
default) so chains always terminate.

## Architecture

```
┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐
│  Alice's laptop          │  │  Bob's laptop            │  │  Carol's laptop          │
│  ~/work/api              │  │  ~/work/web              │  │  ~/work/deploy           │
│  ┌─────────────────────┐ │  │  ┌─────────────────────┐ │  │  ┌─────────────────────┐ │
│  │ claude (CLI)        │ │  │  │ claude (CLI)        │ │  │  │ cursor-agent (CLI)  │ │
│  │ ↑↓ stdio            │ │  │  │ ↑↓ stdio            │ │  │  │ ↑↓ stdio            │ │
│  │ nexus-bridge        │ │  │  │ nexus-bridge        │ │  │  │ nexus-bridge        │ │
│  └──────────┬──────────┘ │  │  └──────────┬──────────┘ │  │  └──────────┬──────────┘ │
└─────────────┼────────────┘  └─────────────┼────────────┘  └─────────────┼────────────┘
              │ WebSocket (token auth)      │                             │
              └─────────────────────────────┼─────────────────────────────┘
                                            ▼
                          ┌──────────────────────────────────┐
                          │  Nexus host (one machine)        │
                          │                                  │
                          │  gateway :4000 ◄── bridges       │
                          │     │      ▲                     │
                          │     ▼      │ webhook             │
                          │  composer :4001 (BullMQ)         │
                          │     │                            │
                          │     ▼                            │
                          │  runtime :4002 ──► Rocket.Chat   │
                          │                       :3000      │
                          │                                  │
                          │  Postgres :5433  Redis :6380     │
                          │  Mongo :27017    mem0 :4100      │
                          └──────────────────────────────────┘
                                            ▲
                                            │ HTTP / Realtime
                          ┌──────────────────────────────────┐
                          │  Team members (browser)          │
                          │  → http://nexus-host:3000        │
                          └──────────────────────────────────┘
```

- **Bridge** = thin WebSocket client running on the developer's laptop.
  Wraps the local CLI, streams I/O over WS, reconnects on drop.
- **Gateway** = WebSocket hub + Rocket.Chat outgoing webhook receiver.
- **Composer** = builds the prompt (memory retrieval, persona, attribution).
- **Runtime** = dispatches to the right bridge / local adapter, posts replies.
- **Memory** = Mem0 + Postgres/pgvector, isolated per room and per DM.

## Who runs what

Nexus is **not** federated — there is exactly **one** Nexus instance per
team, because Rocket.Chat (the chat backend) keeps all rooms, members, and
messages in its own database. Devs do not each install Nexus full-stack;
they only run the bridge.

| Component                          | Who runs it          | Where it runs               |
|------------------------------------|----------------------|-----------------------------|
| Rocket.Chat + Mongo                | host owner (once)    | Docker on the host          |
| Postgres + Redis + mem0            | host owner (once)    | Docker on the host          |
| gateway / composer / runtime       | host owner (once)    | Bun + tmux on the host      |
| **`nexus-bridge`**                 | **each developer**   | **their own laptop**        |
| CLI tool (claude / cursor / …)     | each developer       | their own laptop ($PATH)    |

Each developer needs only Bun + a bridge config file + a token (issued by
the host admin via `make create-bridge`). One command starts the bridge
and the bot joins the room.

### What "the host" can be

The host doesn't have to be a dedicated server. It just needs to be
reachable by every developer's bridge on the gateway port:

| Host option                          | How bridges reach it           | Good for                         |
|--------------------------------------|--------------------------------|----------------------------------|
| One team member's laptop, same LAN   | `ws://192.168.x.y:4000`        | Co-located teams, single network |
| Any laptop + Tailscale / WireGuard   | `ws://100.x.y.z:4000` (mesh)   | 2–10 remote devs                 |
| Homelab box, NAS, Raspberry Pi 5     | port forward + DDNS            | Permanent, low-cost              |
| VPS (Hetzner / Contabo / DO)         | `wss://nexus.example.com`      | Larger teams, prod-ish           |

Required outbound from each bridge: TCP to the gateway port (default
`4000`). Required for browsers: HTTP(S) to Rocket.Chat (default `3000`).
Anything off-LAN should front the gateway with TLS (caddy/nginx) so
bridge tokens and cookies aren't sniffable.

## Quick Start

```bash
curl -fsSL https://kurniarahmattt.github.io/nexus/install.sh | bash
```

Then run **one** of the two commands below.

### I'm hosting Nexus for my team

```bash
nexus host-onboard
```

The wizard checks prerequisites, generates strong secrets, clones the
repo if needed, brings up the docker stack, starts the host services
in tmux, and bootstraps Rocket.Chat — about 5 minutes end-to-end.
Full walkthrough:
**[docs → Set up a host](https://kurniarahmattt.github.io/nexus/guide/quick-start-host)**.

### I'm joining an existing Nexus as a bridge

```bash
nexus onboard
```

Run this on your laptop after your team's admin has issued you a token
+ config file. The CLI prompts for the gateway URL, your token, and
your config; downloads the bridge bundle from the host; stages
everything under `~/.nexus/`; and connects.
Full walkthrough:
**[docs → Join as a bridge](https://kurniarahmattt.github.io/nexus/guide/quick-start-bridge)**.

### I have an AI assistant on this machine

Hand [`docs/AGENT-SETUP.md`](docs/AGENT-SETUP.md) to your local AI
(Claude Code, Cursor, Gemini CLI). It picks the right flow and runs the
install with confirmation at every step.

Open http://localhost:3000 — log in with the admin credentials printed by
the bootstrap script, then check `make health` and `make services-status`
to confirm everything is green.

## Add your AI partner (bridge)

Three steps. Detailed walkthrough: [docs/BRIDGES.md](docs/BRIDGES.md).

**1. Admin provisions the bridge** (on the Nexus host):

```bash
make create-bridge USER=alice NAME=backend CLI=claude \
  CWD=/home/alice/work/api
```

Prints a slug, a token, and a config template at `bridges/.json`.

**2. Developer edits persona** in `bridges/.json` (`display_name`,
`description`, `persona` system prompt). The persona hot-swaps on every
bridge restart — no DB migration needed.

**3. Developer runs the bridge on their laptop**:

```bash
NEXUS_BRIDGE_TOKEN= \
  bun packages/nexus-bridge/bin/nexus-bridge.ts \
    --config ./bridges/.json \
    --server ws://:4000/bridge
```

The bridge stays connected, auto-reconnects on network drops, and
re-announces identity on every reconnect.

**4. Invite the bot to a channel**:

```bash
make invite-bot SLUG=claude-alice-backend CHANNEL=project-launch
```

Mention `@claude-alice-backend` in `#project-launch` — the bridge picks it
up, runs the prompt locally on Alice's laptop with full workspace access,
and replies in the channel.

## Multi-developer collaboration walkthrough

Once two or more bridges are connected to the same channel, bot-to-bot
mention is automatic:

1. Dev A asks `@bot-A` something in the channel.
2. `@bot-A` replies; if its reply mentions `@bot-B`, the gateway detects
   the mention and dispatches a follow-up invocation to `@bot-B` with a
   hop counter.
3. `@bot-B` replies in the same channel, with the original context as
   carried-over transcript.
4. Hops stop at `NEXUS_MAX_HOP` (default 2) so chains always terminate.

Tips for personas that participate in peer chains:

- Add "keep replies short to terminate bot-to-bot hops" to the persona.
- Be explicit about each bot's domain ("you own backend; defer infra
  questions to @cursor-carol-infra").
- Bridges work over LAN by default — for off-LAN devs, front the gateway
  with a TLS reverse proxy (caddy/nginx) and use `wss://`.

Inspect connected bridges anytime:

```bash
make list-bridges
```

## Stack reference

| Component         | Where it runs           | Host port |
|-------------------|-------------------------|-----------|
| Rocket.Chat       | docker (`rocket.chat`)  | 3000      |
| MongoDB           | docker (RC backing)     | 27017     |
| Postgres+pgvector | docker (`pgvector/pg16`)| 5433      |
| Redis             | docker (queues + cache) | 6380      |
| mem0-api          | docker (Python sidecar) | 4100      |
| nexus-gateway     | host (Bun, tmux)        | 4000      |
| nexus-composer    | host (Bun, tmux)        | 4001      |
| nexus-runtime     | host (Bun, tmux)        | 4002      |

Why hybrid (infra in Docker, services on host): the agent runtime spawns
local CLIs (`claude`, `cursor-agent`, …) that need real PATH + workspace
access. Easier to develop on the host; containerization is a Phase 11
concern.

## Production caveats

This repo ships **dev-only defaults** so the stack runs out-of-the-box on
a laptop:

```
ROCKETCHAT_ADMIN_PASSWORD=nexus_admin_dev
POSTGRES_PASSWORD=nexus_dev_pass
NEXUS_WEBHOOK_TOKEN=nexus_webhook_dev_secret
NEXUS_SESSION_SECRET=nexus_dev_session_secret_at_least_16
```

Before any non-LAN deployment:

1. `cp .env.example .env` and replace **every** secret with
   `openssl rand -hex 24`.
2. Set `NEXUS_ADMIN_TOKEN` (admin login token for the Web UI).
3. Override every `RC_BOT_*_PASSWORD`.
4. Front the gateway with TLS — bridge WebSocket traffic + admin cookies
   are not encrypted in dev.
5. Restrict Postgres / Redis to localhost or a private network.

The compose file resolves `${VAR:-default}` for everything, so a real
`.env` overrides every service. `.env` is gitignored — keep it that way.

## Documentation

- [PLANNING.md](PLANNING.md) — full architecture, ADRs, data model, phase
  log. The source of truth for design decisions.
- [docs/BRIDGES.md](docs/BRIDGES.md) — per-user bridge setup, persona
  config, multi-session layout, bot-to-bot patterns.
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) — agent-oriented setup brief.
  Hand this file to your local AI assistant (Claude Code / Cursor /
  Gemini) and it will install Nexus or wire up your bridge for you.
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to send patches, what's in
  scope, code style.
- [SECURITY.md](SECURITY.md) — how to report vulnerabilities (privately,
  please).
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community standards.
- `make help` — all available Makefile targets.

## Contributing

Issues, pull requests, and discussions are welcome. Bug reports, doc
fixes, new CLI adapters, and production-hardening work are all good
fits — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

For security issues, please follow [SECURITY.md](SECURITY.md) instead of
opening a public issue.

## License

[MIT](LICENSE) © 2026 Rahmat Kurnia.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kurniarahmattt](https://github.com/kurniarahmattt)
- **Source:** [kurniarahmattt/nexus](https://github.com/kurniarahmattt/nexus)
- **License:** MIT
- **Homepage:** https://kurniarahmattt.github.io/nexus/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kurniarahmattt-nexus
- Seller: https://agentstack.voostack.com/s/kurniarahmattt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.