NexusDesk
GitHub Contact
15 minutes · Two containers · No model API key

Quick start

This page has one goal: get it running on your machine and walk through a complete support flow. No GPU, no model API key, no need to read the docs first.

First, what you do not need

✓No GPU — the application server needs none; models are called as external services
✓No model API key — trial mode uses a simulated model
✓No Redis — Postgres carries both storage and the task queue
✓No Kubernetes — Docker Compose is enough
✓No Milvus or S3 — trial mode does not depend on them
✓No required reading — one command, then open a browser
Step 1

Requirements

You need

  • Docker
  • Docker Compose v2

Watch out for

  • Docker Desktop must be in Linux container mode — this is the most common cause of a failed start
  • The first run of option 1 needs network access and compiles the front end, which takes a few minutes
Step 2

Pick a way to start it

All three end up in the same place. Options 2 and 3 skip the front-end build and start faster.

Option 1 · Build locally

Run this from the repository root. The first run needs network access and compiles the front end.

sh nexusdesk quickstart

Option 2 · Use the prebuilt image

Skip the front-end build and pull the published image directly.

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

Images are published to both GHCR and Docker Hub with identical content — pick whichever your network prefers. Docker Hub rate-limits anonymous pulls; GHCR does not.

On the version tag: NEXUSDESK_VERSION must be set explicitly, because the default value local only exists for local builds.

Option 3 · Without cloning the repository

Just trying it out? One Compose file is enough. Run this in any directory.

curl -fsSLo compose.yaml \ https://raw.githubusercontent.com/GroundedCore/nexusdesk/main/deploy/quickstart/compose.yaml NEXUSDESK_IMAGE_REGISTRY=docker.io/groundedcore/ NEXUSDESK_VERSION=latest \ docker compose -f compose.yaml up -d

⚠️ Never expose trial mode to the public internet.

To make local evaluation frictionless, trial mode injects an administrative identity when a request carries no credentials. It is intended for your own machine or a trusted intranet only. To serve real traffic, use production deployment with real identity and access control configured.

Step 3

What to do once it is up

Open https://localhost:8080 and go to sample-support in the conversations workbench.

Try a knowledge question

How long does delivery take?

Watch how the agent retrieves from the bound knowledge base, and says it cannot confirm when there is no basis.

Try the ticket flow

Create a ticket for me

Watch the agent draft a ticket that is only created after a human approves it — the write-action safeguard.

Nine industry scenarios are preloaded: retail, enterprise software, manufacturing, education, hospitality, property, logistics, HR and gaming — 9 knowledge bases and 18 agents in total, all prefixed with [case]. Filter for them in the agent list, or just start chatting: they are already bound to a demo model profile.

These scenarios use a simulated model and the interface marks them as demo content. They exist to validate the flow, not to show what a real model would answer.

HTTPS and certificate warnings

Trial mode ships its own self-signed certificate, so access over a LAN IP or internal hostname is still a secure context — browser restrictions on secure-context APIs will not get in your way.

If you hit an error about crypto.randomUUID or the clipboard, it is usually because the page was opened in a non-secure context (http:// on a non-localhost address). Access it over https:// or via localhost.

Troubleshooting

Frequently asked

If your question is not here, tell us and we will add it.

The container exits immediately, or complains about the wrong architecture

The most common cause is Docker Desktop not being in Linux container mode. Switch to “Switch to Linux containers” from the Docker Desktop tray menu and retry.

Port 8080 is already in use

First check for a leftover container with docker ps, or change the port mapping and restart.

Image pulls are slow, or I hit a rate limit

Docker Hub rate-limits anonymous pulls. Point NEXUSDESK_IMAGE_REGISTRY at GHCR instead — the content is identical.

Why do I have to set NEXUSDESK_VERSION at all?

Because there are multiple published versions, and the default local only makes sense for local builds. This is a known piece of friction that we plan to remove.

Without a model API key, what can I actually evaluate?

You can validate the complete flow: knowledge retrieval, tool calls, ticket drafting and human approval, and conversation handoff. The trial model is simulated, so its answers are canned and say nothing about real model quality. To evaluate real behaviour, add a real connection in the model gateway.

The browser says the certificate is not trusted — can I continue?

Yes. It is the self-signed certificate that trial mode generates for local access. Import /data/tls/ca.crt as described above and the warning disappears.

Where is the data stored? Will I lose it if I remove the containers?

Trial mode persists data in named Compose volumes. docker compose down keeps them; adding -v deletes the volumes. Use it carefully.

Can I use this configuration in production?

No. See production deployment: configure role tokens, an external PostgreSQL, and Milvus and object storage as needed.

Where to go next

L2

Configure your own agent

Model profile → knowledge base → agent → publish → chat. See the platform guide in the repository.

Platform guide →

L3

Deploy to production

Role tokens, external PostgreSQL, Milvus and object storage, HTTPS and backups.

Production deployment →

L4

Integrate with your systems

Open platform: applications and keys, signed webhooks, SSE streaming, idempotency keys and call logs.

Open platform docs →