getting started
Run DSUI locally with npx or use the official container image.
Run DSUI on the host for local development and project files.
npx @northgraindata/dsuiDSUI loads ./dsui.yaml when present and stores local state in
~/.local/share/dsui.
Follow the npx quickstart for a complete first-run example. Docker is an alternative when you need process isolation or are already using Compose.
On first start, DSUI generates and persists a local encryption key at
~/.local/share/dsui/.master-key, so UI-managed connections work without extra
setup. Keep this file with the local data directory. Set DSUI_MASTER_KEY
explicitly when you need to control key storage in Docker, CI, or a
multi-instance deployment.
DSUI ships as a container image on GitHub Container Registry. It needs no separate database or control plane.
docker pull ghcr.io/northgraindata/dsui:latestdocker run --rm -p 4192:4192 -v dsui-data:/data \
ghcr.io/northgraindata/dsui:latestThis starts an empty workspace. Open http://localhost:4192 to verify that DSUI
is running, then add DSUI_CONFIG and mount a dsui.yaml when you are ready to
connect services. The quickstart shows the
configured path.
The /data volume holds DSUI’s local state and any file-backed data you mount
there. DSUI does not start the services declared in dsui.yaml; it connects to
services that are already running.
To host the UI below a URL prefix, build the image with
--build-arg DSUI_WEB_BASE_PATH=/demo/ and configure the reverse proxy to route
/demo to the container with prefix stripping enabled. The default / keeps
the standard root-hosted behavior.
Docker is intentionally isolated from the host. If an adapter requires an executable or runtime, provide it in the image used to run DSUI. Host binaries are not available inside the official image.
For a configured workspace with adapters, use the quickstart.
Contributors can run DSUI from a checkout with Bun 1.3.12.
git clone https://github.com/northgraindata/dsui.git
cd dsui
bun install --frozen-lockfile
bun run dev