fork-setup

name	fork-setup
description	Get DGX Lab running on your own DGX Spark after cloning or forking. Covers prerequisites, install, config, first run, Docker, Tailscale, and common troubleshooting. Use when setting up DGX Lab for the first time or diagnosing setup issues.

Fork Setup — Getting DGX Lab Running

Prerequisites

Requirement	Check
NVIDIA DGX Spark (or GPU with nvidia-smi)	nvidia-smi returns GPU info
Python 3.12+	python3 --version
uv	uv --version
Bun 1.3+	bun --version
Docker + Docker Compose (production only)	docker compose version

Install and first run

git clone <your-fork-url> dgx-lab && cd dgx-lab
cd backend && uv sync && cd ..
cd frontend && bun install && cd ..
make dev

Open http://localhost:3000. Backend is at http://localhost:8000/api/health.

Configuration

All paths are set via env vars in backend/app/config.py. Defaults work out of the box on a Spark:

Env var	Default	What
DGX_LAB_MODELS_DIR	~/.cache/huggingface/hub	HuggingFace model cache
DGX_LAB_EXPERIMENTS_DIR	~/.dgx-lab/experiments	Logger experiment data
DGX_LAB_TRACES_DIR	~/.dgx-lab/traces	Agent trace JSONL files
DGX_LAB_DATASETS_DIR	~/.dgx-lab/datasets	Local dataset storage
DGX_LAB_MEMORY_TOTAL_GB	128	Total memory for fit calculations
DGX_LAB_MEMORY_BW_MAX_GBS	273	Memory bandwidth ceiling

If your machine has different specs (e.g. a non-Spark GPU), override the memory vars:

export DGX_LAB_MEMORY_TOTAL_GB=80
export DGX_LAB_MEMORY_BW_MAX_GBS=200

Docker (production)

make build
make up

Serves on port 80 via nginx. Stop with make down. Logs with make logs.

Remote access (Tailscale)

# On the Spark
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale serve http://localhost:80

# From your Mac
open https://spark.your-tailnet.ts.net

See docs/remote-access.md for SSH tunnels and systemd auto-start.

Troubleshooting

Problem	Fix
uv sync fails	Ensure Python 3.12+. Run uv python install 3.12 if needed.
bun install fails	Ensure Bun 1.3+. Run curl -fsSL https://bun.sh/install | bash to update.
Monitor shows "GPU not available"	Verify nvidia-smi works on the host. In Docker, add deploy.resources.reservations.devices for GPU access.
Frontend can't reach backend	Dev mode proxies /api/* via Next.js rewrite to localhost:8000. Ensure backend is running.
Docker build fails on frontend	Ensure bun.lock exists. Run bun install locally first to generate it.
Port 80 already in use	Change the nginx port in docker-compose.yaml: ports: ["8080:80"]

Project layout (quick reference)

backend/app/main.py        ← FastAPI app, router registration
backend/app/config.py      ← All env vars and hardware constants
backend/app/routers/*.py   ← One router per tool
frontend/apps/web/app/     ← Next.js pages (app router)
frontend/apps/web/components/ ← UI components per tool
frontend/packages/ui/      ← Shared shadcn components
docker-compose.yaml        ← frontend + backend + nginx
nginx.conf                 ← Reverse proxy config
Makefile                   ← dev, build, up, down, logs, rebuild