Introducing NukeLab: Multi-User Scientific Computing for Nuclear Engineering

Every nuclear engineer knows the tax: before you can run a single particle transport simulation, you spend days — sometimes weeks — compiling toolchains. OpenMC, DAGMC, MOAB, Geant4, NJOY, each with its own build flags and dependency maze. Then a colleague asks you to reproduce your environment, and the meter starts over.

NukeHub exists to delete that tax. Our mission has always been to let the global nuclear community “focus on designing the clean energy systems of tomorrow by transforming months of software configuration into seconds of cloud deployment.” NukeLab is where that mission becomes a product you can log into.

NukeLab is a multi-user scientific computing platform with granular role-based access control, real-time monitoring, credit-based resource management, and dynamic container orchestration^nukelab-repo. It gives every user an on-demand, browser-accessible nuclear-engineering workspace — a full IDE with the simulation stack preinstalled — while giving administrators the governance tools to run it all safely on shared hardware. You can self-host it on a single Docker or Podman machine, or sign in to our hosted instance at lab.nukehub.org.

NukeLab v2.0 shipped on May 1, 2026^{nukehub-changelog}. It is a ground-up rewrite that replaces the JupyterHub-based v1 with a custom orchestration layer: a FastAPI backend, a React 19 dashboard, PostgreSQL 17, Redis 7, Celery workers, and Traefik v3 routing. The numbers behind it today: 52+ API endpoints, 6 predefined RBAC roles, 4 resource plans, and a backend test suite that has grown from 500+ tests at launch to over 2,600.

This post is the full tour: how workspaces work, how the credit economy keeps shared hardware fair, how the security model is layered, what the observability stack sees, which platforms are supported, and what is coming next.

The three building blocks: Environments, Plans, Servers

Everything in NukeLab is built from three concepts:

• Environments are admin-defined templates describing a Docker image (or a custom Dockerfile), the installed tools and packages, exposed ports, environment variables, volumes, and resource defaults. An environment is the what — for example, “NukeIDE with OpenMC and Geant4.”
• Plans are resource tiers: how much CPU, memory, and disk a server gets, plus max runtime, idle timeout, and the hourly cost in NUKE credits. A plan is the how big. Decoupling plans from environments means you can run the same toolchain at four different sizes without duplicating anything.
• Servers are the per-user workspaces themselves: isolated containers spawned on demand from an environment + plan pair, each with persistent storage and its own routed URL.

The user-facing workflow is deliberately boring:

1. Sign in with local credentials or your organization’s OAuth2/OIDC provider.
2. Pick an environment and a plan, then deploy — NukeLab validates your permissions, quotas, and credit balance before anything starts.
3. Open NukeIDE in your browser and run your simulations.
4. Invite collaborators into shared workspaces, watch live metrics, and let scheduled start/stop handle the routine.

Under the hood, a spawn request flows through authentication, permission, quota, and credit checks, then into the ResourcePoolService, which verifies the host actually has the CPU, memory, and disk to honor the plan. If it does not, the request is queued rather than failed — fair scheduling for scarce hardware. Otherwise the spawner ensures the persistent volume, pulls the image, creates the container with the plan’s cgroup limits, attaches Traefik labels so it is reachable at /user/<username>/<server>, waits for an HTTP readiness probe, and flips the server to running while broadcasting a status event over WebSocket to every open dashboard.

Servers move through a well-defined lifecycle — pending, starting, running, stopping, stopped, error — with a background HealthCheckService that probes running containers and can automatically restart unhealthy ones. Idle servers are stopped after their plan’s idle_timeout, hard-stopped at max_runtime, and cron-based schedules (fired by Celery Beat) can start and stop servers on a timetable — say, powering up a lab environment every weekday at 08:00 and shutting it down at 18:00 to stop burning credits. A Quick Spawn shortcut (Alt+N) with saved defaults makes the common case one keystroke.

Fair-share resource plans

Plans are how NukeLab turns one physical machine into a shared platform without the noisy-neighbor problem. The four built-in tiers:

One thing to know about these defaults: all four built-in plans ship private — visible only to administrators — and the admin decides which of them to make available to users, retuning any value first: specs, hourly cost, runtime limits, everything. Treat the table as the factory starting point, not a fixed menu.

The limits are real, enforced by the kernel: cgroup v2 CPU throttling and core pinning, hard memory ceilings, and storage quotas on XFS, ZFS, or Btrfs. Inside the container, lxcfs makes free and nproc report the plan’s limits instead of the host’s, so tools that auto-size thread pools or memory caches behave correctly. On top of plans, per-user quotas (max_cpu, max_memory, max_disk, max_servers) cap what any single account can hold at once, and GPU fields are already in the data model ahead of the GPU scheduling work on the roadmap.

NUKE: a credit economy for shared hardware

Shared academic hardware always ends up with the same politics: someone leaves a 16-core job idling for a week, and everyone else queues. NukeLab’s answer is a small internal currency.

Every user has a NUKE balance and a daily allowance that refills each day — with no rollover, deliberately, so credits cannot be hoarded. While a server runs, Celery workers debit the balance at the plan’s hourly rate. Run out of credits and spawning or starting a server is refused until the next allowance lands or an admin issues a grant. Every movement goes through an append-only, immutable CreditTransaction ledger typed as daily_allowance, server_usage, admin_grant, purchase, or refund, so balances are always auditable down to the last credit.

The result is a platform where a classroom of thirty students can share one workstation fairly: everyone gets daily compute, heavy users think about what they run, and administrators get a lever (admin_grant) for exceptions without touching quotas.

Inside the workspace: NukeIDE

The container you land in is not a bare shell. The flagship workspace environment runs NukeIDE — our open-source IDE built on Eclipse Theia 1.72.3^theia, designed specifically for nuclear simulation and engineering^{nuke-ide-repo}. It ships three purpose-built extensions on top of the full Monaco-based editing experience:

• OpenMC Studio (flagship): a no-code graphical builder for OpenMC Monte Carlo simulations^openmc-docs — materials, CSG geometry, a DAGMC editor with faceting and volume grouping, tallies with mesh editors and filter builders, depletion, variance reduction, photon transport, parameter-sweep optimization, CAD import (STEP/IGES to DAGMC or CSG), and Python script export. Live simulation dashboards plot k-eff as the run progresses.
• Nuke Visualizer: 3-D/2-D visualization for nuclear data — VTK, DAGMC .h5m, STL, PLY, and OBJ meshes; OpenMC statepoint viewing with k-eff convergence plots; tally overlays on geometry; energy spectra; and source-distribution scatter plots.
• Nuke Core: the foundation — automatic detection and management of conda, mamba, venv, poetry, pyenv, and uv environments, package installs with live terminal output, health checks, and a context-aware status bar.

NukeIDE also ships with Theia’s AI assistant built in (chat, code completion, and terminal assistance, with providers from OpenAI and Anthropic to local Ollama and Llamafile), plus VS Code extension compatibility through Open VSX — the Microsoft Python and Jupyter extensions come preconfigured. When it runs inside NukeLab, a dedicated nukelab-integration extension wires the IDE to the platform: it knows your username and server, adds “Back to Dashboard” and “Log Out” commands, and lets you install the workspace as a PWA. If you prefer a native window, the same IDE exists as an Electron desktop app for Windows, macOS, and Linux^{nuke-ide-page}.

The environment images themselves are layered, each built on the previous:

1. base — a digest-pinned Debian 13 image with nginx and the auth sidecar, running as the unprivileged nukelab user.
2. dev — adds a ttyd web terminal, for lightweight shell-only workspaces.
3. workspace — adds Miniforge (conda), Node.js, and the NukeIDE browser build.
4. radiation-transport — the full nuclear stack, compiled from source: OpenMC v0.15.3, DAGMC v3.2.4, MOAB 5.5.1, Geant4 v11.4.2, double-down v1.1.0, libMesh v1.8.4, NJOY2016 2016.79, KDSource v0.2.2, PyNE, and ALARA, plus ParaView, pythonocc-core, paramak, PlasmaPy, NCrystal, montepy, geant4-pybind, vmecpp, pydagmc, and mcpl on the Python side.

That last layer is the “months of configuration” the mission statement talks about, collapsed into docker pull. Admins can also define entirely custom environments — the template system accepts any image or Dockerfile — and build the provided ones with ./nukelabctl build env <name>.

Architecture: boring on purpose

NukeLab is engineered for constrained, self-hosted bare metal — a university server under a desk, not a cloud region. Every piece is a well-understood, boring-in-a-good-way component:

Traefik’s routing table is the whole traffic story in three rules: / serves the static SPA, /api and /ws go to FastAPI, and /user/<username>/<server> is dynamically routed to the right user container via Docker labels — no config reloads as servers come and go.

The design decisions behind this stack are documented in the repo, and they are opinionated: a Vite SPA instead of Next.js because there is no Node.js runtime overhead in production; FastAPI instead of Django because async WebSockets matter for streaming Docker stats; Traefik instead of Nginx because container auto-discovery eliminates an entire class of proxy config^traefik; PostgreSQL with monthly partitioning instead of a separate time-series database.

RBAC: six roles, one permission matrix

Multi-user means governance, and NukeLab’s model is granular: six predefined roles, over twenty permissions editable through a visual permission-matrix editor, per-user permission overrides for exceptions, and 24 granular scopes for API tokens.

Administration happens from a single panel: bulk start/stop/restart/delete across servers, workspace and volume management, IP allowlists and blocklists with CIDR support (and self-block prevention, so you cannot lock yourself out), scheduled maintenance windows with automatic enable/disable, a notification center with over twenty event types delivered in-app, by email, and over WebSocket, and full audit logging with CSV/JSON export. Impersonation exists for support workflows but is restricted to super_admin and written to the audit log like everything else.

Security in layers

A platform that proxies you into a container as another user on a shared host has to get isolation right. The layered model:

• Identity: local username/password (bcrypt) or OAuth 2.0/OIDC with PKCE — Keycloak, Auth0, Okta, Authentik — or both at once. Access tokens are short-lived JWTs signed with EdDSA (Ed25519), published via JWKS, with zero-downtime key rotation (./nukelabctl rotate-user-auth-key) and a Redis-backed denylist for revocation.
• Container access: opening a workspace issues a separate, server-scoped RS256 token valid for five minutes, validated inside the container by a small Go auth-sidecar that holds only the public key — no per-request calls back to the platform, and no user credentials ever enter the workspace container.
• Web hardening: CSRF double-submit protection, security headers, path-traversal defenses, two-layer rate limiting (per-IP at Traefik, per-user in the API), and audit logging of administrative actions.
• Container hardening: workspaces run as a non-root UID with all capabilities dropped, a read-only root filesystem, and no-new-privileges — verifiable at any time with ./nukelabctl verify-hardening.

An internal OWASP Top 10 audit has passed, and a full third-party penetration test is scheduled before the public launch — one of the few remaining gates on the roadmap.

Observability: see everything, opt in to more

Out of the box, the dashboard streams live CPU, memory, disk, and network metrics over WebSocket — global, per-user, and per-server — with usage-trend charts over 7, 30, and 90 days and configurable alert rules. That is the always-on tier.

Flip on the monitoring overlay and NukeLab grows a full Prometheus stack: Prometheus scraping custom nukelab_* metrics (HTTP request rates and durations, active WebSocket connections, cache hit ratios, user and server counts, total NUKE balance), two provisioned Grafana dashboards (API performance and infrastructure), Alertmanager with pre-built rules for high error rate, high p99 latency, target down, and Postgres/Redis saturation, and optional OpenTelemetry tracing into Jaeger. None of it gets host ports — Grafana lives at /grafana and Prometheus at /prometheus, behind Traefik ForwardAuth, so the observability stack inherits the platform’s own authentication.

Two quieter pieces complete the picture. Error tracking runs through the Sentry SDK on both frontend and backend — a no-op until you set a DSN, with self-hosted GlitchTip as the recommended target. And every log line is structured JSON carrying a correlation ID, which doubles as the trace ID when OpenTelemetry tracing is enabled, so you can follow a single spawn request from the HTTP edge through the API, the database, and the Docker daemon.

Self-host in five minutes

Prerequisites: Docker or Podman with compose, Git, and about 10 GB of free disk.

git clone https://github.com/nukehub-dev/nukelab.git
cd nukelab
cp .env.example .env.development
./nukelabctl start

That is the whole thing. The dashboard comes up at http://localhost:8080, the API docs at http://localhost:8080/api/docs, and a development admin account (admin / admin123) is created automatically in dev mode. nukelabctl is the single entry point for operating the platform:

./nukelabctl dev          # hot-reload dev stack (Vite dev server on :5173)
./nukelabctl test         # backend pytest suite, in containers
./nukelabctl e2e          # Playwright end-to-end tests
./nukelabctl loadtest     # Locust + k6 load profiles
./nukelabctl lint all     # ruff, eslint/prettier, shellcheck, markdown
./nukelabctl security     # Bandit, pip-audit, npm audit, SBOM
./nukelabctl backup       # database backup (restore <file> to revert)
./nukelabctl doctor       # host-readiness diagnostics

Quality engineering is treated as a feature, not an afterthought: over 2,600 backend tests covering security, lifecycle, and performance paths; hybrid Locust + k6 load testing with smoke, baseline, stress, spike, and endurance profiles; CI that lints, tests, builds, and pushes signed images with Trivy vulnerability scans, Cosign signatures, and SBOMs attached.

Platform support: Docker and Podman today, k3s tomorrow

Since deployment targets keep coming up, here is the support matrix, stated plainly:

• Supported today: a single Linux host running Docker or Podman with Compose — the container engine is auto-detected, and the same compose.yml drives both. For production-grade isolation the host needs cgroup v2 controllers (cpu cpuset io memory pids), lxcfs, and a quota-capable filesystem — XFS, ZFS, or Btrfs; ext4 and overlayfs cannot enforce the per-container storage quotas. TLS is handled by Traefik with automatic Let’s Encrypt certificates.
• Hosted alternative: if you would rather not run anything at all, lab.nukehub.org is the same platform operated by NukeHub.
• Planned for Q4 2026: k3s / Kubernetes deployment — Helm charts, horizontal pod autoscaling, PVCs, Network Policies, and Pod Security Standards. The project’s own rule is to reach for Kubernetes only once a single node is saturated (think a 32-core / 128 GB server), and the monitoring docs already sketch the migration path onto kube-prometheus-stack with ServiceMonitor and PrometheusRule CRDs. Cross-host server migration stays parked until that multi-node work lands.

And when you need a human: talk.nukehub.org for questions and discussion, or the GitHub issue trackers on nukelab and nuke-ide for bugs and feature requests.

What is next

The public roadmap^{nukehub-roadmap} tracks where the platform goes from here. In progress for Q3 2026:

• Environment image pipeline — CI-driven builds with registry tagging, immutable image versions, and automated base-image refreshes (today images are built manually).
• Playwright E2E suite — browser tests for login, server spawn/stop, workspace sharing, and admin bulk actions.

Planned for Q4 2026:

• k3s / Kubernetes deployment — Helm charts, horizontal pod autoscaling, PVCs, Network Policies, and Pod Security Standards, for when a single node is no longer enough.
• GPU allocation & metrics — GPU scheduling in plans and quotas, device passthrough, and GPU metrics in the dashboard (deferred until the CPU orchestration path is complete; the data model is already GPU-aware).

On the NukeIDE side that powers the workspaces: OpenMC Studio Phase 5 (a Random Ray/MOC deterministic solver, multi-group cross-section generation, kinetics parameters, and advanced source types), the optimization framework’s full parameter-sweep pipeline, a Cardinal multiphysics extension coupling OpenMC with MOOSE in Q4 2026, and Geant4 integration in Q1 2027. MCNP support is parked — gated by licensing and distribution constraints, not by interest.

Try it

NukeLab is open source and ready to run today:

• Hosted instance: lab.nukehub.org — sign in and deploy a server in minutes.
• Source: github.com/nukehub-dev/nukelab and github.com/nukehub-dev/nuke-ide — stars, issues, and pull requests welcome.
• Community: talk.nukehub.org — come tell us what you are simulating.

NukeHub runs on the generosity of sponsors, donors, and volunteers. If NukeLab saves your team weeks of setup, consider giving back through the Support Us page^{nukehub-support}: yearly sponsorship tiers from Bronze ($250/year) to Platinum ($2,500/year) plus custom packages, one-time donations, resource donations of server capacity or infrastructure, and volunteering — from contributing code and writing tutorials to leading workshops. Contributions fund server capacity, feature development, and educational programs, and sponsors are recognized on the acknowledgment page.

Whether you are a professor who needs thirty identical OpenMC environments for a reactor-physics course, a lab that wants its simulation toolchain off individual laptops, or a student who just wants to run a pin-cell benchmark without compiling MOAB first — NukeLab was built for you. Deploy a server and see.