English | 简体中文

NexusDock

The self-hosted control center for your AgentDock fleet.

Bring the AgentDock instances running on your Macs, Windows PCs, servers, and containers into one Web console and one MCP endpoint. Manage devices, shared Recall, reusable workflows, and live runtime state without exposing every machine directly to the internet.

AgentDock · Releases · Docker Hub · GHCR

What is NexusDock?

NexusDock is a self-hosted control center for people who run AgentDock on more than one device.

AgentDock remains the execution layer on each machine: it owns files, commands, Git, Skills, dynamic MCP servers, browser automation, tasks, and other device-local capabilities. NexusDock adds the shared layer above those nodes:

• one Web console for the fleet;
• one MCP endpoint for AI clients;
• centralized Recall and workflow templates;
• live views of node runtime state;
• pairing, routing, authentication, and shared settings.

NexusDock does not replace AgentDock and does not copy every node's runtime state into a second control plane. Nodes keep their own execution state and connect outbound to NexusDock.

              ChatGPT / Claude / Codex
                        │
                        │ MCP + OAuth / Access Token
                        ▼
                 ┌─────────────┐
                 │  NexusDock  │
                 │ Web + MCP   │
                 └──────┬──────┘
                        │
              outbound node connections
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
   ┌───────────┐ ┌───────────┐ ┌───────────┐
   │ AgentDock │ │ AgentDock │ │ AgentDock │
   │    Mac    │ │  Windows  │ │   Server  │
   └───────────┘ └───────────┘ └───────────┘

        Shared Recall · Workflows · Settings

What can NexusDock do?

• View the online state, version, and capabilities of multiple AgentDock nodes
• Pair, rename, disable, and remove devices from one place
• Inspect node-local tasks, Skills, and dynamic MCP servers without duplicating their state
• Store and search shared Recall, experience cards, and private notes
• Publish, retire, match, and reuse workflow templates across devices
• Expose one MCP endpoint that combines NexusDock-owned shared tools with routed AgentDock capabilities
• Authenticate MCP clients with OAuth or a dedicated MCP Access Token
• Configure optional Embedding and model providers for semantic Recall and workflow matching
• Generate temporary download links for files published by online AgentDock nodes

Quick start

The easiest way to run NexusDock is Docker Compose. Create compose.yaml:

services:
  nexusdock:
    image: agentdockio/nexusdock:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:18777:18777"
    volumes:
      - nexus-data:/var/lib/nexus
      - recall:/recall
volumes:
  nexus-data:
  recall:

Create the administrator and start NexusDock:

docker compose run --rm nexusdock admin init admin
docker compose up -d

Open http://127.0.0.1:18777 and sign in with the account you just created. For remote access, HTTPS, API authentication, and backup settings, see Security notes and Data, ports, and backup.

The same image is also available from ghcr.io/uvwt/nexusdock:latest. Official images support linux/amd64 and linux/arm64.

Pair AgentDock devices

Sign in to the Web console, open Settings → System & nodes, and choose Pair device.

NexusDock creates a short-lived, single-use pairing code and shows a command similar to:

agentdock nexus pair --endpoint https://nexus.example.com --code pair_xxx

Run it on the target device and follow the prompt to restart AgentDock. The node then connects outbound to NexusDock, so you do not need to expose the AgentDock node itself to the public internet.

Pairing does not change the node's existing local MCP endpoint or authentication. Each AgentDock instance can still be used independently.

Connect an AI client

NexusDock exposes MCP Streamable HTTP at:

https://your-nexus-domain/mcp

Clients with OAuth support can connect directly and complete authorization in the browser.

For clients that need a fixed token, open Settings → MCP access and use the dedicated MCP Access Token:

Authorization: Bearer <MCP Access Token>

The common credentials are intentionally separate:

Credential	Purpose
Administrator username and password	Sign in to the Web console; protected management APIs are accessed through the signed-in session
MCP Access Token	Access to /mcp for clients that do not use OAuth

Resetting the MCP Access Token invalidates the previous fixed token immediately and does not affect OAuth clients.

Core capabilities

Fleet and runtime

• Central device list with connection state, version, and capabilities
• Short-lived pairing codes and outbound AgentDock connections
• Explicit node selection before viewing node-local runtime state
• Live task, Skill, and dynamic MCP views routed to the selected AgentDock
• Temporary Artifact downloads through the existing node connection while the source node is online

Recall and workflows

• Shared Markdown Recall workspace
• Keyword search and optional semantic retrieval
• Experience cards and vector recall
• Private-note vault with age-encrypted backup copies
• Central workflow template registry with versioned publish, retire, list, get, and match operations

NexusDock does not automatically configure or push a Git remote for Recall. Remote backup remains under the deployment owner's control.

MCP gateway

• One MCP endpoint for NexusDock-owned shared tools and enabled AgentDock nodes
• OAuth authorization for compatible MCP clients
• Dedicated fixed MCP Access Token for clients without OAuth
• Node-aware routing without requiring inbound public AgentDock ports
• Shared protocol contracts with AgentDock through uvwt/agentdock-protocol

AI and vector settings

Embedding and external model integrations are optional. Configure them from Settings → AI & vectors when you need semantic Recall, workflow vector matching, or related AI-assisted features.

Without an Embedding or model provider, device management, MCP routing, Recall file browsing, keyword search, and basic workflow operations continue to work.

Data, ports, and backup

Path	Purpose
/var/lib/nexus	NexusDock control-plane state, accounts, devices, sessions, settings, secrets, and workflow data
/recall	Shared Recall content and private-note data

Default HTTP port:

18777

Before upgrading, back up both persistent stores. The quick-start Compose file uses the Docker volumes nexus-data and recall; if you switch to bind mounts, back up both host directories in full.

nexus-data/
recall/

Upgrade with:

docker compose pull
docker compose up -d
curl http://127.0.0.1:18777/health

Do not run two NexusDock instances that write to the same Nexus data store.

Optional: repository Compose template

The Quick Start above is the default recommended path. You do not need to use the repository Compose file. If you clone the repository and want to manage additional site settings through .env, the repository Compose template reads these values:

Variable	Example default	Description
NEXUS_DATA_DIR	./nexus-data	Host directory mounted to /var/lib/nexus
RECALL_REPO_DIR	./recall	Host directory mounted to /recall
NEXUS_PUBLIC_URL	empty	Public HTTPS origin, for example https://nexus.example.com
NEXUS_TRUSTED_PROXIES	127.0.0.1,::1	Proxies allowed to supply trusted X-Forwarded-* headers
NEXUS_HTTP_BIND	127.0.0.1	Host listen address; the container port is fixed at 18777
NEXUS_HTTP_PORT	18777	Host port; the container port is fixed at 18777
NEXUS_IMAGE	empty	Image tag pinned for production, for example ghcr.io/uvwt/nexusdock:sha-<short SHA>; falls back to nexusdock:local

NEXUS_DATA_DIR and RECALL_REPO_DIR above are host bind-mount sources. Inside the official image, NexusDock always uses /var/lib/nexus and /recall.

See .env.example for the repository Compose values. Existing custom Compose deployments can keep using their own configuration; no migration to the repository template is required.

Direct binary and advanced deployment

When running the NexusDock binary directly, these additional environment variables control the process itself:

Variable	Default	Description
NEXUS_HOST	127.0.0.1	HTTP listen address
NEXUS_PORT	18777	HTTP listen port
NEXUS_LOG_LEVEL	info	debug, info, warn, or error

The four Compose variables above are also valid process environment variables when running the binary directly. In that case, NEXUS_DATA_DIR and RECALL_REPO_DIR are application data paths rather than Docker mount sources.

Security notes

For a remote deployment, administrator login requires HTTPS. Direct localhost / loopback access is the only HTTP exception.

• keep the container port bound to loopback and publish the service through HTTPS;
• set NEXUS_PUBLIC_URL to the real HTTPS origin;
• trust only the reverse proxies that actually sit in front of NexusDock;
• use a strong administrator password and access protected management APIs through the signed-in session;
• restrict host access to nexus-data and recall;
• use the MCP Access Token only for /mcp, never for management APIs.

The official image runs as UID/GID 10001:10001 and is designed to work with a read-only root filesystem, dropped Linux capabilities, and no-new-privileges.

If you forget the administrator password:

docker compose run --rm nexusdock admin recover

Development and contribution

Clone the repository and build both the Web UI and Go service:

git clone https://github.com/uvwt/nexusdock.git
cd nexusdock
make web-deps
make build

Run the normal checks before submitting code:

make check

Run the full CI-equivalent verification when preparing a complete change:

make ci

Changes to shared AgentDock/NexusDock contracts may also require coordinated updates to uvwt/agentdock-protocol and uvwt/agentdock.

Submit bugs and feature requests through GitHub Issues.

Related links

• AgentDock
• NexusDock Releases
• Docker Hub
• GitHub Container Registry
• agentdock-protocol