English · 简体中文 · Website

Chinese-speaking users: see the 简体中文 README.

An open-source, self-hostable, and extensible general-purpose agent platform.

NexusDesk is built to reduce the cost and difficulty of moving AI from a capability demo into a stable, measurable business service. Its first complete open-source reference application is AI customer service, which validates the platform against real workflows rather than a technical demo.

NexusDesk is organized into four layers:

The shared execution loop is:

Request → retrieve context → decide → call tools → human confirmation → execute → record → evaluate

Agents retrieve knowledge, call business tools, and decide what to do next based on execution results. The Harness handles permissions, execution boundaries, memory, human handoff, and audit. It is not another agent; it is the engineering control layer around the agent execution loop.

The default deployment requires only PostgreSQL. PostgreSQL handles data storage, job queues, and cross-process messaging. Redis, dedicated message queues, Kubernetes, and other infrastructure can be added as throughput, latency, isolation, or availability requirements grow. The initial deployment still starts with one Compose file.

Quickstart · Production deployment · Core capabilities · Architecture

Requires Docker and Docker Compose v2. On Docker Desktop, use Linux containers.

Option 1: build locally. The first run requires network access and compiles the frontend.

# Linux / macOS
sh nexusdesk quickstart

# Windows PowerShell
.\nexusdesk.ps1 quickstart

Option 2: use the published image.

NEXUSDESK_IMAGE_REGISTRY=docker.io/groundedcore/ NEXUSDESK_VERSION=latest \
  docker compose -f deploy/quickstart/compose.yaml up -d

Open https://localhost:8080 and choose the sample-support conversation:

• Enter 发货需要多久？ to try knowledge Q&A.
• Enter 帮我创建工单 to try drafting, human confirmation, and ticket creation.

The quickstart uses a self-signed certificate, so the browser will warn on first access. See the deployment guide for certificate setup and LAN access.

Nine industry case sets are also included: 9 knowledge bases, 18 agent drafts, and 36 documents. Every resource name carries the [案例] prefix and can be filtered on the Agent page.

Security note: the quickstart uses a mock model and does not represent real answer quality. The default credentials admin / nexusdesk are for local evaluation only and are not an authentication boundary. Keep the default 127.0.0.1 binding; if you expose the service, restrict access with a security group or firewall.

Copy the configuration template, fill in role tokens and the external PostgreSQL connection, and enable Milvus / S3 as needed:

# Linux / macOS
cp deploy/production/.env.example deploy/production/.env
# Edit deploy/production/.env
sh nexusdesk deploy

# Windows PowerShell
Copy-Item deploy/production/.env.example deploy/production/.env
# Edit deploy/production/.env
.\nexusdesk.ps1 deploy

Open http://localhost:8080 and enter the configured role token under Access and Policy. The platform can start without a default model; configure and publish a Chat profile, bind it to an agent, and then start a conversation.

The production topology includes six long-running services — API, Runtime Worker, Channel Worker, Knowledge Worker, Memory Worker, and Web — plus a one-shot migration task. See the deployment guide for HTTPS, backup, upgrade, and external access configuration.

Typical flow: customer asks a question → the agent retrieves knowledge or calls a tool → the result is returned → a human handoff or confirmed ticket creation follows as needed.

When an agent can read tool results and adjust its next action, not every business path needs to be fixed as a complete workflow up front. NexusDesk focuses on:

• Dynamic decisions where they fit: within configured limits, the agent chooses knowledge retrieval or tool calls, and ReAct feeds execution results into the next decision.
• Explicit boundaries for high-impact actions: permissions, parameter validation, execution limits, and human confirmation are not left to the model.
• Infrastructure that scales on demand: PostgreSQL is the default requirement; Milvus and S3 are optional, and dedicated middleware or cluster capabilities can be added as scale or availability requirements grow.

NexusDesk is not a knowledge Q&A chatbot, a traditional workflow engine that fixes every path in advance, or a generic agent builder that leaves execution governance to application developers. Paths that must remain deterministic stay under deterministic control.

• Retrieval: the runtime defaults to keyword search; Milvus vector retrieval is not yet validated end to end.
• Tools: built-in tools and HTTP integrations are available; the MCP adapter is still planned.
• Quickstart: uses a mock model, connects to no real business system, and does not represent real model quality.
• Deployment: Docker Compose only; no Kubernetes or Helm charts yet.
• Overall status: the project is under continuous development and is not production ready out of the box. See the module delivery notes.

flowchart LR
    Console[React console] --> API[FastAPI service]
    Channels[Business systems and channels] --> API
    API --> PG[(PostgreSQL)]
    API --> Workers[Runtime / Channel / Knowledge / Memory Workers]
    Workers --> Gateway[Model gateway]
    Workers --> Tools[Tool gateway]
    Workers --> Retrieval[Knowledge retrieval]
    Gateway --> Models[Model APIs]
    Tools --> Business[Business APIs]
    Retrieval --> PG
    Retrieval --> Milvus[(Milvus, optional)]

NexusDesk is a modular monolith: the API and workers share one backend codebase and are deployed as separate processes. PostgreSQL stores business data and the task queue; Milvus, S3, and an external parsing service are enabled per feature.

Using external model services requires no GPU on the application server. See the middleware guide for details.

The documents listed below are currently written in Simplified Chinese.

NexusDesk keeps its platform core and extension contracts open, validates platform capabilities through real applications, and turns that experience into reusable, maintainable product capabilities.

The public roadmap has two complementary tracks:

See the module architecture for module-level plans.

Contributions are welcome through issue reports, documentation improvements, test cases, and code.

• Use the issue templates and include reproduction steps, deployment mode, and sanitized logs.
• Read the contributing guide before contributing code.
• Use Discussions for design-level topics.

Do not include API keys, access tokens, or customer privacy data in issue reports, screenshots, or code.

This project is licensed under the Apache License 2.0.