Configuration

dsui.yaml describes the services DSUI should load at startup.

services:
  - id: local-duckdb
    adapter: duckdb
    name: Local DuckDB
    connection:
      method: memory
      readOnly: false

id must be kebab-case. adapter selects a loaded adapter. connection is validated by that adapter before DSUI connects.

Complete local example

This is a complete file-backed DuckDB setup. The DuckDB file and DSUI’s local state live in the dsui-data Docker volume, so both survive container restarts.

Project layout:

.
├── compose.yaml
└── dsui.yaml

Create dsui.yaml:

services:
  - id: warehouse
    adapter: duckdb
    name: Analytics warehouse
    connection:
      method: file
      path: /data/warehouse.duckdb

Create compose.yaml next to it:

services:
  dsui:
    image: ghcr.io/northgraindata/dsui:latest
    ports:
      - "4192:4192"
    environment:
      DSUI_CONFIG: /etc/dsui/dsui.yaml
    volumes:
      - ./dsui.yaml:/etc/dsui/dsui.yaml:ro
      - dsui-data:/data

volumes:
  dsui-data:

Start the workspace:

docker compose up -d

Open http://localhost:4192, select Analytics warehouse, and open Query. You can now run SQL against /data/warehouse.duckdb.

Stop the container without removing its data:

docker compose down

Use docker compose down -v only when you also want to delete the DuckDB file and DSUI’s persisted local state.

Configuration is read by the DSUI process, while credentials should come from environment variables. In Docker, the /data volume persists DSUI state and file-backed databases; in the npx runtime, local state lives under ~/.local/share/dsui.

DSUI automatically generates ~/.local/share/dsui/.master-key for local UI-managed connections. Do not delete or replace it if the data directory contains saved connections. For controlled deployments, provide a stable 32-byte base64 key through DSUI_MASTER_KEY and keep it in your secret store.

Connect an existing stack

The same file can declare several services. Use the Compose service name as the host when DSUI and the service run in the same Compose project. Put credentials in the environment rather than committing them to dsui.yaml.

services:
  - id: postgres
    adapter: postgresql
    name: Application database
    connection:
      host: postgres
      database: app
      username: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

  - id: airflow
    adapter: airflow
    name: Airflow
    connection:
      method: airflow
      baseUrl: http://airflow:8080
      username: ${AIRFLOW_USERNAME}
      password: ${AIRFLOW_PASSWORD}

Each service gets its own adapter context and appears as a separate service in the DSUI workspace. Adding a service here does not start that service; it tells DSUI how to connect to one that is already running.

Secrets

Use environment variables for credentials.

connection:
  baseUrl: http://airflow:8080
  username: ${AIRFLOW_USERNAME}
  password: ${AIRFLOW_PASSWORD}

Missing variables stop startup. Never commit credentials. Services declared in dsui.yaml are read-only in the DSUI service manager.

Add an adapter package

Source checkouts include the preview adapters. A published community adapter must be exact and integrity-pinned.

adapters:
  example:
    package: "@your-org/dsui-adapter-example"
    version: "0.1.0"
    integrity: "sha512-..."