Nexus Docs

nexus import scans the current workspace for pre-existing agentic configuration files (CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, .windsurf/rules/*.md, GEMINI.md) and imports them into the linked Nexus project. This is the recommended way to onboard existing projects alongside the platform-managed workflow.

During nexus init, the CLI automatically detects existing agentic files and offers to run the import. The import can also be triggered manually at any time via nexus import.

The CLI creates a .nexus/ directory in your project root to store workspace metadata, project bindings, and cached configuration. This directory is automatically excluded from Git via .git/info/exclude (not .gitignore) to avoid polluting the shared ignore file. The nexus deinit command cleans up both the cache directory and the exclude entries.

Preserves Nexus session context across OpenCode compaction events and records each compaction as an auditable entry in the active Nexus session. Ensures resuming agents have full context even after context window compaction.

Tracks token usage and estimated cost for the current Nexus session by aggregating data from OpenCode's native AssistantMessage objects. No external dependencies — all data is sourced locally from the OpenCode session.

On load, each plugin shows a TUI toast confirming its name, version, and API connection status. Use the /nexus-show-plugins command to display detailed plugin information on demand.

The plugin is distributed as a code-mirror— the TypeScript source lives in each project's .opencode/plugins/ directory. It is not published to npm. Updates are synced via nexus pull (agent files mechanism). Requires @opencode-ai/plugin as a dependency (auto-managed via .opencode/package.json).

OpenCode plugins are only distributed to projects where the agent owner is set to opencode or both. Projects using claude-cli exclusively will not receive plugin files during nexus pull.

API tokens use the nxs_pat_* prefix and are passed as Bearer tokens in the Authorization header. Tokens are SHA-256 hashed at rest and resolve to a user identity with tenant and project scope.

Nexus uses a dual-layer RBAC model: (1) platform-level roles via app_metadata.platform_role (platform_owner, platform_admin), and (2) project-scoped roles via project_memberships (owner, admin, developer, viewer). Customer-level access is managed through customer_memberships.

A Workspace Blueprint is a global template that defines a complete dev environment. It combines a baseline (core packages like go, node, python), a flavor (curated package sets like nexus-dev), and 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. A database trigger tracks upstream changes so you can pull updates when ready.

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

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

The CLI uses the v2 fork API with automatic fallback to v1 for backwards compatibility. Upstream changes are surfaced during nexus status so you can decide when to sync.

Creating a blueprint uses a 5-step wizard: Type (Devbox 0.17, with Dev Containers and devenv coming soon), Baseline, Flavor, Post-Init Script, and Metadata. Blueprints can be activated, deactivated, or archived. Only active blueprints appear in the project assignment modal.

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.

The devbox.json file is the heart of every Nexus workspace. It defines a reproducible, Nix-based development environment that is consistent across all team members and CI pipelines. When a workspace fork is pulled via the CLI, Nexus materializes this file in your project root.

Structure

{
  "packages": [],      // Nix packages (array or object)
  "env": {},           // Environment variables
  "shell": {
    "init_hook": [],   // Commands run on shell start
    "scripts": {}      // Named scripts (devbox run <name>)
  },
  "include": []        // Plugin references
}

Key Sections

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 (via env_from) for secrets.
• Prefer the map format for packages when using platform-specific or plugin options.
• Document custom scripts with clear names (e.g. dev, test, build).
• Use Nexus Meta Variables (C_DBX_*) to inject project-level config into the environment at fork level.

Validation

The Nexus workspace editor validates your 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. Errors block the save; warnings are informational.

See the official Devbox configuration reference for the full specification.