Workspaces

Reproducible, version-controlled development environments using Devbox.

Nexus Workspaces follow a Blueprint + Fork architecture: admins create global blueprints, and projects receive independent deep-copy forks that can be customized without affecting the source.

Blueprint + Fork architecture

A Workspace Blueprint is a global template that defines a complete dev environment. It combines:

A baseline — core packages like Go, Node, or Python
A flavor — curated package sets like nexus-dev or web-frontend
Optional post-init scripts and metadata variables

When assigned to a project, Nexus creates a Fork — a deep copy of the blueprint at its current version. Forks are fully independent: changes to the composed body, post-init script, or meta variables do not propagate back to the blueprint.

Wizard

Creating a blueprint uses a 5-step wizard:

Type — Devbox 0.17 (Dev Containers and devenv coming soon)
Baseline — core language runtime
Flavor — curated package bundle
Post-Init Script — setup commands
Metadata — project-level variables

Blueprints can be activated, deactivated, or archived. Only active blueprints appear in the project assignment modal.

Baselines and flavors

Baselines provide the foundation packages. Flavors add curated tool sets on top. Both are admin-seeded and read-only.

Type	Examples	Purpose
Baseline	`go-1.23`, `node-22`, `python-3.12`	Core language runtime
Flavor	`nexus-dev`, `web-frontend`, `data-science`	Curated package bundle

CLI integration

The Nexus CLI pulls workspace forks and materializes them as local Devbox configuration files:

Command	Description
`nexus pull --scope workspace`	Download the active workspace fork and write `devbox.json` + init scripts
`nexus status`	Shows workspace fork status including upstream change detection

Files written by nexus pull

nexus pull writes or updates the following files in the .nexus/ workspace cache:

File	Description	Git-tracked
`AGENTS.md`	Auto-generated agent identity and role definition	No
`CLAUDE.md`	Claude-specific agent context and cross-reference	No
`skills/*.md`	Cached skill files for offline reference and IDE autocompletion	No
`.nexus/env`	Plugin configuration vars (`HEADROOM_*`, etc.) — non-sensitive, fully overwritten on every pull	No
`opencode.json`	MCP server config, plugin assignments, and Headroom MCP block	Project-dependent

.nexus/env is the platform-managed source for all OpenCode plugin environment variables. It is git-ignored and must never be edited manually — changes in the Nexus dashboard propagate here on the next nexus pull. Use nexus run to launch OpenCode with these vars automatically injected into the child process.

devbox.json reference

The devbox.json file is the heart of every Nexus workspace. It defines a reproducible, Nix-based development environment.

{
  "packages": [],
  "env": {},
  "shell": {
    "init_hook": [],
    "scripts": {}
  },
  "include": []
}

Key sections

Name
packages
Type
array | object
Description
Nix packages. Supports version pinning (go@1.23), flake references, and per-platform filtering.
Name
env
Type
object
Description
Environment variables set inside the Devbox shell. Supports $PWD and $PATH.
Name
shell.init_hook
Type
array
Description
Shell commands run before every devbox shell or devbox run.
Name
shell.scripts
Type
object
Description
Named commands runnable via devbox run <name>.
Name
include
Type
array
Description
References to Devbox plugins (GitHub repos, local paths, or built-in).

Best practices

Pin package versions explicitly (e.g. node@22 instead of node@latest) for reproducible builds
Keep init_hook fast — move long-running setup into named scripts
Use env for project-specific config; use .env files for secrets
Use Nexus Meta Variables (C_DBX_*) to inject project-level config at fork level

Validation

The Nexus workspace editor validates devbox.json in real-time: JSON syntax errors are caught immediately, and devbox-specific rules (valid top-level keys, package format, platform names, shell structure) are checked before saving.

Upstream change detection

When a blueprint is updated after a fork has been created, a database trigger sets upstream_changed = true on all forks of that blueprint. This flag is visible in both the UI and the CLI, letting project teams decide when to pull the latest changes.