Quickstart

Get Nexus running with your agent in under two minutes.

Step 1: Create a project

Sign in at nexus.gatewarden.eu with GitHub. From the dashboard, click New Project and give it a name. You will receive a project ID and an API token — keep these handy.

Step 2: Install nexus-cli

After creating your project, the dashboard shows a one-line install command. Run it in your terminal:

curl -fsSL https://nexus.gatewarden.eu/install.sh | sh

Verify the installation:

nexus --version

Step 3: Initialize your workspace

Navigate to your project directory and run:

nexus init

This command:

• Creates a .nexus/ directory (your local workspace cache)
• Pulls your project's agent files, skills, and directives
• Writes opencode.json (or equivalent) with the MCP server config
• Installs nexus-mcp automatically

Step 4: Enable cost control (optional)

Nexus supports two token-saving tools that are auto-configured when enabled in the dashboard. After nexus init you can activate them:

Headroom — Context Compression

pip install "headroom-ai[mcp]"
headroom --version    # verify

nexus init (or a subsequent nexus pull) writes .nexus/env with the project's HEADROOM_* plugin configuration and updates opencode.json with the Headroom MCP server block.

Launch OpenCode with plugin vars injected:

nexus run             # recommended — injects .nexus/env, then starts opencode

Or use devbox shell if you have a Nexus workspace — dbx_init.sh sources .nexus/env automatically on shell start.

See nexus run and nexus-headroom-intercept for full details.

Step 5: Start a session

Open your AI coding agent (OpenCode, Claude Code, or any MCP-compatible tool). The nexus-mcp server is now available. Run the init skill to start a tracked session:

/nexus-init

Your agent will load project context, check for open sessions, and begin tracking work.

Next steps