Ports​

nginx in Docker terminates port 80 and proxies to the frontend and /api/ to FastAPI. Dev mode skips nginx and exposes Next directly on 3000 and the API on 8000 (proxied by Next for browser calls).

Same LAN​

On the Spark:

hostname -I

Use the relevant address from your Mac or other client:

http://<spark-ip>:3000    # development
http://<spark-ip>         # Docker / nginx on :80

No extra software if routing and firewalls allow it.

Tailscale​

Install Tailscale on the Spark and on the client, authenticate both to the same tailnet, then use the Spark’s Tailscale hostname or IP from tailscale status:

http://<spark-tailscale-hostname>:3000   # dev
http://<spark-tailscale-hostname>        # production/docker

The README also describes tailscale serve for HTTPS-style URLs on your tailnet and tailscale ssh for shell access — useful when you need to restart make dev or inspect logs without physical access.

SSH local forward​

If Tailscale is not an option and you can SSH to the Spark:

# On your Mac or laptop
ssh -L 3000:localhost:3000 -L 8000:localhost:8000 <user>@<spark-ip>

Then open http://localhost:3000 locally. Keep the session open; when it drops, the tunnel drops.

Security posture (stated plainly)​

DGX Lab is meant for private networks. The backend uses permissive CORS because the expected clients are your own devices, not arbitrary internet origins. Do not expose port 80 or 3000 to the public internet without putting something in front that you trust.

Further reading​

• Repo guide: docs/remote-access.md (systemd example, same content family).
• Architecture diagram and stack: Introducing DGX Lab.
• First-time setup: First run on your Spark.

Model and experiment data​

If a directory does not exist yet, create it or run the tool that populates it — the backend does not magically scaffold all of these on first boot.

Agent, transcripts, and LangSmith​

These paths support the in-dashboard agent, RAG index, and trace export — they are easy to miss if you only read the “eight tools” table.

Set these explicitly when you run multiple clones, store caches on another volume, or keep transcripts in a non-default Cursor layout.

Memory display constants​

Unified memory on the Spark is 128 GB with a ~273 GB/s bandwidth ceiling in product messaging. DGX Lab uses those numbers for gauges and “fit” math unless you override:

If you run the same codebase on different hardware (not the intended case, but possible), adjust these so the UI does not lie about headroom.

The same constants feed the memory fit story in Control: a typical 70B Q4 load against the 128 GB pool looks like the breakdown below (illustrative segments — your cache and workload will differ).

Why this matters​

• Control and Monitor tie directly to GPU visibility and cache paths — wrong DGX_LAB_MODELS_DIR means an empty library or wrong sizes.
• Logger / Traces / Datasets are pure filesystem contracts — if the path is wrong, the UI is empty, not “broken.”
• Agent behavior depends on DGX_LAB_CODEBASE_ROOT and index dir — a mismatched root indexes the wrong tree.

Link related reading: Introducing DGX Lab for architecture context; repo README.md duplicates the high-level table for quick grep.

Prerequisites​

If you are following along from a laptop that is not the Spark, you still need the repo on the Spark for GPU-backed tools and local paths. SSH in, clone there, open the UI from the Spark browser or from your Mac via LAN/Tailscale (see the remote access post).

Install​

From the repo root on the machine that will host the app:

git clone https://github.com/jxtngx/dgx-lab.git ~/dgx-lab
cd ~/dgx-lab

cd backend && uv sync && cd ..
cd frontend && bun install && cd ..

uv sync respects backend/uv.lock. bun install uses the workspace package.json under frontend/.

Development​

make dev

That brings up FastAPI on port 8000 and Next.js on port 3000. The dev frontend proxies /api/* to the backend, so you usually open:

http://localhost:3000

From another device on the same LAN, use the Spark’s IP: http://<spark-ip>:3000.

Production-style Docker​

make build
make up

nginx listens on port 80 and routes / to the frontend container and /api/ to FastAPI. Use make down, make rebuild, and make logs as needed; the README summarizes each target.

When something fails​

The setup guide mirrors these steps. The codebase and docs/ are the source of truth — there is no ticket queue.

Expectations​

Per CONTRIBUTING.md, this repo is a personal project: issues and PRs are not triaged. Forks are encouraged if you need different defaults or tools. The modular layout (one router per tool under backend/app/routers/, one route under frontend/apps/web/app/(tools)/) exists so you can adapt without waiting on a maintainer.

make dev

If that command succeeds and http://localhost:3000 loads, you are past the hardest part.

This post walks through what it is, what it runs on, and how it fits together.

The hardware​

The DGX Spark is a desktop with a GB10 Grace Blackwell SoC: an Arm-based Grace CPU and a Blackwell GPU sharing 128 GB of unified memory at roughly 273 GB/s. FP4, FP8, and FP16 precision. No discrete VRAM -- the memory pool is shared between CPU and GPU, which changes how you think about model loading and inference budgets.

Memory budget​

128 GB sounds like a lot until you load a 70B model. Quantization helps -- a 70B at Q4 fits in around 38 GB, leaving room for KV cache, activations, and the system overhead. DGX Lab's Control tool shows this breakdown for every model in your HuggingFace cache.

The chart above shows a typical allocation when serving a 70B Q4 model. The "Available" segment is what's left for additional workloads, experiments, or a second model.

The tools​

DGX Lab ships eight tools, each backed by a FastAPI router and rendered by a Next.js page:

Every tool that touches model loading or training reasons about the 128 GB budget. Control shows memory fit bars. Monitor tracks GPU utilization in real time. AutoModel validates that a training recipe will fit before launching.

The stack​

Frontend:   Next.js 16  ·  React 19  ·  Tailwind CSS 4  ·  shadcn v4
Backend:    FastAPI  ·  Python 3.12  ·  uv
Deploy:     Docker Compose  ·  nginx  ·  Tailscale
Hardware:   DGX Spark  ·  GB10 Grace Blackwell  ·  128 GB LPDDR5X
Agent:      LangChain  ·  Claude 3.5 Haiku (Bedrock)  ·  FAISS + cuVS  ·  LangSmith

The frontend is a Turborepo monorepo with Bun workspaces. apps/web is the Next.js app; packages/ui holds shared shadcn components. The backend runs on the Spark itself -- FastAPI with async routers, one per tool. Docker Compose bundles frontend, backend, and an nginx reverse proxy. Tailscale provides remote access from a Mac or any device on the tailnet.

Architecture​

The DGX Lab Agent is a RAG-backed assistant that treats the entire codebase as its knowledge base. It uses nvidia/llama-embed-nemotron-8b for embeddings, FAISS with cuVS GPU acceleration for vector search, and nvidia/llama-nemotron-rerank-1b-v2 for reranking. The LLM is Claude 3.5 Haiku via AWS Bedrock. All interactions are traced with LangSmith.

Design language​

Dark base. Cyan is earned -- active states, live-status dots, critical metrics only. Monospace for machine data, sans for navigation and prose. Density over decoration. The dashboard should feel like it was built by someone who runs large models at 2am, not a marketing team.

What's next​

DGX Lab is open source under Apache 2.0. Clone it, fork it, adapt it for your hardware. The architecture is modular: adding a tool means one FastAPI router, one Next.js page, one sidebar entry.

git clone https://github.com/jxtngx/dgx-lab.git
cd dgx-lab
make dev

The docs cover setup, tool guides, and API reference. The codebase is the documentation.