Setup

Choose the backend before configuring QDash: Fake runs without quantum hardware, while Qubex connects QDash to a supported lab system.

Choose a Backend

Goal	Setup path
Evaluate QDash without quantum hardware	Fake backend
Operate a Qubex-connected lab deployment	Qubex backend
Connect another hardware stack	Under construction — the current release accepts only fake and qubex; another backend requires QDash code changes, not deployment settings.

Both supported paths use the same Docker Compose stack. The backend choice changes the available calibration tasks and whether the workflow worker opens a hardware connection.

Host-side API and UI processes are a development workflow. Use Development Environment Setup instead of this page when changing QDash code.

Prepare the Host

Install Git, Docker, and Docker Compose. Go Task is optional; every required setup command has a Docker Compose equivalent.

Clone the stable branch. The repository default is develop, so select main explicitly:

git clone --branch main https://github.com/oqtopus-team/qdash.git
cd qdash

The main branch contains stable releases. Do not use develop, a feature branch, or a prerelease tag for an operational installation. Follow System Updates to move an existing installation to another release.

Next, complete either the Fake backend or Qubex backend configuration. Each path creates the .env file used by the remaining steps.

Configure Shared Deployment Settings

Set a unique initial administrator password in .env before exposing QDash to a network.

Variable	Purpose
QDASH_ADMIN_USERNAME / QDASH_ADMIN_PASSWORD	Initial administrator login
API_PORT / UI_PORT / PREFECT_PORT	Host ports for the API, UI, and Prefect
MONGO_DATA_PATH / POSTGRES_DATA_PATH	Persistent database directories
CALIB_DATA_PATH	Calibration figures, raw data, and run artifacts
CLIENT_URL	Public UI URL used in links generated by QDash
NEXT_PUBLIC_DEFAULT_THEME	Initial UI theme for browsers without a saved preference

The example files also list optional AI provider, Slack, knowledge repository, and tunnel settings. Leave an optional credential empty when that integration is not in use.

Configure AI

The AI runtime and its workspace start with the standard Compose stack. Internal authentication is generated automatically; no AI service profile or UI enable flag is required.

Set the OPENAI_COMPATIBLE_BASE_URL_CHAT and OPENAI_COMPATIBLE_API_KEY_CHAT pair in .env for chat, and the corresponding EVALUATION pair for figure analysis. Base URLs must include /v1. Select models in config/copilot/chat.yaml and config/copilot/evaluation.yaml.

Copilot can propose supported write operations without an extra enable setting. The signed-in user must approve each proposed write in the chat, and their project permissions still apply. The retired AGENT_RUNTIME_ENABLE_WRITE_TOOLS variable has no effect and can be removed from existing .env files.

Authenticate AI endpoints with Cloudflare Access

Use one Cloudflare Access service token for chat and figure analysis. Create the token and add it to a Service Auth policy on each AI endpoint's Access application, following Cloudflare's service token instructions.

Set the shared credentials in .env:

CF_ACCESS_CLIENT_ID=<service-token-client-id>
CF_ACCESS_CLIENT_SECRET=<service-token-client-secret>

Keep the existing OPENAI_COMPATIBLE_BASE_URL_CHAT and OPENAI_COMPATIBLE_BASE_URL_EVALUATION settings pointed at the protected HTTPS URLs, including /v1. The shared token is sent to every endpoint configured through base_url: env:OPENAI_COMPATIBLE_BASE_URL_<SUFFIX>, including custom suffixes. Literal URLs and built-in providers do not receive it.

Keep each endpoint's API key if the model server requires it. If authentication is handled only by Cloudflare Access, leave that API key empty. Both Access values must be set together; leave both empty to keep using API-key-only authentication.

After changing .env, recreate the runtime to load the values:

docker compose up -d --build --force-recreate agent-runtime

Set the Default Color Theme

Set NEXT_PUBLIC_DEFAULT_THEME to light, dark, cupcake, emerald, corporate, synthwave, nord, night, dracula, dim, abyss, business, coffee, or sunset. An unsupported value falls back to light.

A theme selected from Settings is saved in the browser and takes precedence. This variable is embedded in the UI image at build time; rebuild the UI after changing it:

docker compose build ui
docker compose up -d ui

Start QDash

Validate the resolved Compose configuration, then build and start the enabled services:

docker compose config --quiet
docker compose up -d --build

If Go Task is installed, task deploy-local performs the startup and also pulls the optional knowledge repository configured by KNOWLEDGE_REPO_URL.

Application logs use Docker named volumes. The Pi runtime stores resumable conversation state in the agent-runtime-state volume. Normal container recreation preserves both.

Verify the Installation

Confirm that the containers are running:

docker compose ps

Open these services using the ports from .env:

• QDash UI: http://localhost:5714/login
• API documentation: http://localhost:5715/docs
• Prefect: http://localhost:4200

Sign in with QDASH_ADMIN_USERNAME and QDASH_ADMIN_PASSWORD. For a Fake deployment, create a chip, then continue with Running Calibrations. For Qubex, confirm the intended chip and hardware configuration before starting a task.

Enable Remote Access

Set CLIENT_URL to the public UI URL, set TUNNEL_TOKEN, and enable the tunnel Compose profile.

CLIENT_URL=https://qdash.example.com
TUNNEL_TOKEN=<cloudflare-tunnel-token>
COMPOSE_PROFILES=tunnel

Start the stack again with docker compose up -d --build. task deploy is the equivalent Go Task command; it enables the tunnel while preserving profiles already configured in .env.