Skip to main content

Agents

An agent is a database document plus runtime config — not a compiled Rust type. You create one in the UI by filling in fields; Nexus Core stores it and makes it available for scheduling.

Creating an agent (UI shape)​

name: Backend Implementer
slug: backend-implementer
description: Implements backend features in Rust, TypeScript, or C#.

model:
  provider: openai
  model: gpt-5.5-thinking
  temperature: 0.2

runtime:
  image: nexus-agent-runner:latest
  cpu: "2"
  memory: "4Gi"
  timeout_minutes: 60

skills:
  - rust-backend-development
  - mongodb-schema-design
  - api-test-writing
  - git-branch-workflow

# Repositories are NOT defined on the agent. They live on the board (project) a
# task belongs to — agents are a shared, repo-agnostic pool. See Boards.

memory_scopes:
  - global
  - project
  - agent_private

tools:
  - git
  - shell
  - cargo
  - npm
  - kubectl-readonly
  - board-comment

permissions:
  can_create_branch: true
  can_commit: true
  can_open_pr: true
  can_merge: false
  can_delete_files: false
  requires_human_approval_for:
    - production_deploy
    - dependency_upgrade
    - database_migration

No Rust code changes to add this agent — it's a document.

Repositories live on the board, not the agent​

Agents are a shared, repo-agnostic pool. An agent does not carry its own repositories — the GitHub repos a run clones come from the board (project) the task belongs to. The same agent therefore builds many different projects in parallel; which repos it sees is decided entirely by the board its task is on.

See Boards for how a board declares its repositories (and its Taiga mapping). At run time the worker resolves the task's board, and the runner clones each of the board's repos side-by-side into /workspace/<name>, injecting a "Repositories" section into the system prompt.

Back-compat

An agent may still carry a legacy repositories list; it is used only as a fallback when the board declares none. Prefer moving repos onto the board.

Private https repos are authenticated with a token the runner reads from the agent secret (GIT_TOKEN, falling back to GITHUB_TOKEN / GITLAB_TOKEN); SSH URLs use the mounted SSH key. See Security for how to provide these. Edit the repository list any time from the agent editor in the Admin UI.

MCP servers (external tools)​

Beyond Nexus's built-in and platform tools, an agent can pull in external MCP servers. Each agent carries an mcp_servers list; at run time their tools are merged into the agent's toolset (namespaced <server>.<tool>) for both API and CLI backends.

FieldMeaning
nameLogical name; namespaces the server's tools.
commandExecutable to launch (must exist in the agent image / on PATH).
argsCommand arguments.
envExtra environment variables for the server process.
toolsOptional allow-list of tool names to expose; empty = all.
disabledKeep the definition but skip starting it.

Only stdio servers (launched as subprocesses) are supported — confined pods have no general egress. See Tools → External MCP servers for how discovery and merging work per backend. Edit the list from the agent editor in the Admin UI.

Stored document​

{
  "_id": "agent_backend_implementer",
  "name": "Backend Implementer",
  "slug": "backend-implementer",
  "status": "enabled",
  "description": "Implements backend tasks.",
  "model": {
    "provider": "openai",
    "model": "gpt-5.5-thinking",
    "temperature": 0.2
  },
  "runtime": {
    "type": "kubernetes_job",
    "image": "nexus-agent-runner:latest",
    "cpu": "2",
    "memory": "4Gi",
    "timeout_minutes": 60
  },
  "skills": ["rust-backend-development", "mongodb-schema-design"],
  "repositories": [
    { "url": "https://github.com/acme/backend.git", "name": "backend", "branch": "main" },
    { "url": "https://github.com/acme/docs.git", "name": "docs", "read_only": true }
  ],
  "memory_policy": {
    "read_scopes": ["global", "project", "agent_private"],
    "write_scopes": ["project", "agent_private"],
    "auto_save": true
  },
  "tools": ["git", "shell", "cargo", "board-comment"],
  "permissions": {
    "can_commit": true,
    "can_open_pr": true,
    "can_merge": false
  },
  "created_at": "2026-05-30T00:00:00Z",
  "updated_at": "2026-05-30T00:00:00Z"
}

Agents page (UI)​

Features:

  • Create agent · Clone agent · Enable / disable agent
  • Assign skills · Choose model · Choose tools · Choose memory scopes
  • Set Kubernetes resources · Set approval rules · View agent performance

Suggested table columns:

Name | Type | Status | Model | Skills | Active Runs | Success Rate | Last Run

How an agent becomes a run​

At dispatch time, Nexus Core:

  1. Loads the agent definition from MongoDB.
  2. Loads the attached skills.
  3. Searches memory (per the read scopes) for relevant context.
  4. Builds the runtime prompt/config, including the agent's repository list.
  5. Creates a Kubernetes Job using the agent's runtime image and resources. The runner clones every configured repository into the workspace before the agent starts.

The pod doesn't branch on agent type — it receives the config payload. See Agent run.