[ getting started · 1 of 3 ]

Install & first run

Stand up NVTrader on a fresh NVIDIA DGX Spark (or any CUDA 12.x host) in about ten minutes. The install does conda env + repo skeleton + dependencies + cuFOLIO clone + a GPU smoke test before the FastAPI server comes up on port 8015.

Requirements

What	Minimum	Recommended	Why it matters
GPU	any CUDA 12.x (compute 8.0+)	NVIDIA DGX Spark · GB10	cuFOLIO scenario gen + cuOpt PDLP + NemoRL all hit the GPU. CPU fallback works but is 30–100× slower.
OS	Linux (Ubuntu 22.04+)	Ubuntu 22.04 LTS	Docker base image + cuDNN are aligned to 22.04.
RAM	16 GB	32 GB	Backtest sweeps + NemoRL training hold the full universe in memory.
Disk	20 GB free	100 GB free	Audit log + sim ledger + RL policies grow over time.
Network	egress to `integrate.api.nvidia.com`	add `data.alpaca.markets`, Tavily, Finnhub	NVIDIA Build proxies Nemotron + Kimi K2.6. Broker + data providers need their own endpoints.
Python	3.11	3.11 (conda)	cuOpt, alpaca-py, and webull-openapi all pin against 3.11.

Docker compose (recommended)

The one-line install on a fresh GB10 host:

git clone https://github.com/BenikaH/traderspace.git && cd traderspace
bash scripts/setup.sh --mode docker

This invokes the multi-stage Dockerfile and:

detects GPU vs CPU automatically (passes --gpus all if present)
scaffolds .env with chmod 600 and stubbed credentials
builds on nvidia/cuda:12.3.0-runtime-ubuntu22.04 (~10 min first time, then cached)
brings the app up on http://localhost:8015
polls /api/health until it returns 200 before exiting

Compose profiles

Flag	Adds
`--profile postgres`	Postgres for production-grade auth (drop-in replacement for the default SQLite at `data/auth.db`).
`--profile phoenix`	Arize Phoenix UI at `:6006` + OTel Collector. Browses the NAT spans graphically.
`--profile all`	Enables both above.

Conda (dev mode)

Use this if you intend to modify the codebase. Same end state, but you keep direct access to uvicorn --reload and the test suite.

conda create -n traderspace python=3.11 -y
conda activate traderspace
pip install -e ".[dev]"
git clone https://github.com/NVIDIA/cufolio.git extern/cufolio
pip install -e extern/cufolio
python scripts/cufolio_smoke_test.py     # verify cuOpt PDLP solves cleanly
uvicorn traderspace.api.chat_server:app --host 0.0.0.0 --port 8015 --reload

tip

If cufolio_smoke_test.py falls back to CPU, your CUDA driver is older than the one PyTorch was built against. Either upgrade the driver or set CUFOLIO_FORCE_CPU=1 while you sort it.

Environment variables

NVTrader reads its config from a .env file at the repo root and overrides via process env. The most important ones:

Var	Required?	Default	Effect
`NVIDIA_API_KEY`	yes	n/a	NVIDIA Build auth. Walks Nemotron Super + Nano Omni + Kimi K2.6.
`CHAT_MODELS`	no	`moonshotai/kimi-k2.6,nvidia/nemotron-3-super-120b-a12b`	Ordered fallback chain for the PM chat.
`BROKER`	no	`sim`	One of `sim · alpaca · webull · ibkr · tradier`.
`ALPACA_KEY_ID` / `ALPACA_SECRET`	if broker=alpaca	—	Stored encrypted at rest via Fernet once linked through the UI.
`ALPACA_PAPER`	no	`true`	Set to `false` to use the live Alpaca endpoint. Do not do this until you have verified the account.
`AUTH_DB_URL`	no	`sqlite:///data/auth.db`	Set to a Postgres URL to migrate auth transparently.
`JWT_SECRET`	generated	random per-host	Persisted to `data/.auth_secret`, chmod 600.
`TAILSCALE`	no	—	If set, the app binds to `0.0.0.0:8015` so the tailnet can reach it.

danger

.env is gitignored. Never commit it. data/.auth_secret is also chmod 600 and gitignored — losing it makes all encrypted API keys unreadable.

GPU smoke test

Confirm cuFOLIO + cuOpt see the GPU before you start the server:

python scripts/cufolio_smoke_test.py

Expected output:

device     = cuda:0 (NVIDIA DGX Spark · compute 12.1)
scenarios  = 5000 (KDE on GPU)
solver     = cuOpt PDLP
solve time = 251 ms  ← LP solve
weights    = [0.21 0.18 0.14 ...]  ← sums to 1.0
✓ smoke OK

If you see device = cpu instead, NemoRL will still train but cuFOLIO solves will run 30–100× slower. Verify with nvidia-smi; check torch.cuda.is_available().

Open http://localhost:8015. The landing page auto-redirects to /login.html.

The first user to register is automatically promoted to admin.
Pick any email + password (bcrypt hashed; JWT session lasts 12h).
You land on the Portfolio dashboard with an empty SimBroker portfolio ($100k starting cash).
Go to Account → API keys to link real providers, or jump to the Setup Wizard.

That's the whole bootstrap. From here, see Setup wizard or your first backtest.

Troubleshooting

Symptom	Cause	Fix
`/api/health` never returns 200	Port 8015 in use	Either `lsof -i :8015` and kill, or set `PORT=8016` in `.env`.
cuFOLIO falls back to CPU	CUDA driver mismatch	`nvidia-smi` shows driver version. Match to `nvcc --version` or use the Docker path.
NemoRL kicks but exits at 0 steps	SB3 missing	`pip install stable-baselines3[extra] gymnasium`
Chat says "no models configured"	`NVIDIA_API_KEY` missing	Get one at `build.nvidia.com`; paste into `.env`; restart.