Agent configuration

Understanding nexus.yaml

Every Nexus agent is defined by a YAML manifest called nexus.yaml, generated during nexus init. This file controls every aspect of your agent's behavior: which model it uses, what tools it can access, how long it remembers, and what guardrails constrain its actions.

Basic structure

# nexus.yaml
name: code-architect
model: nexus-1
context_window: 128k

memory:
  persistent: true
  retention_days: 90

tools:
  - compiler
  - test_runner
  - code_search
  - docs_retriever

guardrails:
  require_review: true
  allowed_paths: ["src/", "tests/"]
  max_parallel_tasks: 3

Each section specifies a different aspect of agent behavior. Let us examine each one.

Memory settings

The memory section controls persistent memory behavior. persistent: true enables cross-session memory. retention_days controls how long memories are retained before compaction. For sensitive projects, you can disable persistent memory entirely:

memory:
  persistent: false

Tool configuration

Tools are the agent's interface to your development environment. Each tool is independently configurable:

tools:
  - compiler
  - test_runner
  - code_search
  - docs_retriever
  - static_analysis
  - dependency_resolver

You can also configure tool-specific options:

tools:
  compiler:
    language: typescript
    strict_mode: true
  test_runner:
    timeout: 120
    parallel: true

Guardrails

Guardrails enforce safety boundaries. The most important settings are:

require_review: When true, the agent generates plans but waits for human approval before executing changes. allowed_paths: Restricts file system access to specific directories. max_parallel_tasks: Limits concurrent operations to prevent resource exhaustion.

Custom instructions

You can provide custom instructions that guide the agent's behavior:

instructions: |
  Always prefer functional programming patterns.
  Write tests for every new function.
  Use the Result type for error handling.
  Follow the existing code style in each module.

These instructions are injected into the agent's system prompt on every invocation.

Complete YAML reference

The full nexus.yaml schema supports the following top-level fields:

# nexus.yaml - complete reference
name: my-agent              # required: agent name (slug)
model: nexus-1              # model: nexus-1, gpt-5, claude-4
context_window: 128k        # or 32k, 64k, 256k

memory:
  persistent: true          # enable cross-session memory
  retention_days: 90        # days before compaction
  tier: full                # full | compact | minimal

tools:                      # list of enabled tools
  - compiler
  - test_runner
  - code_search
  - docs_retriever
  - static_analysis
  - dependency_resolver
  - git_ops
  - package_manager

guardrails:
  require_review: true      # pause before file modifications
  allowed_paths:            # restrict filesystem access
    - "src/"
    - "tests/"
    - "docs/"
  max_parallel_tasks: 3     # concurrency limit
  allowed_hosts:            # restrict network access
    - "api.github.com"
    - "registry.npmjs.org"

review:
  approvers:                # required reviewers for changes
    - "lead-engineer"
  auto_approve_patterns:    # skip review for these
    - "*.test.ts"
    - "*.md"

notifications:
  slack: "#agent-updates"   # Slack webhook URL or channel
  email: "team@company.com"

Advanced configuration patterns

For production deployments, consider these advanced patterns. Multi-environment configuration: Use YAML anchors and environment variables to manage different configs for dev/staging/prod:

# nexus.yaml with environment substitution
model: ${NEXUS_MODEL:-nexus-1}
memory:
  retention_days: ${NEXUS_RETENTION:-90}
guardrails:
  require_review: ${NEXUS_REQUIRE_REVIEW:-true}
  allowed_paths: ${NEXUS_ALLOWED_PATHS:-["src/","tests/"]}

Environment variables are resolved at agent startup. Variables prefixed with NEXUS_ are automatically loaded. Use the :-default syntax for fallback values.

Configuration profiles: Split configuration into profiles for different use cases:

nexus deploy --name my-agent --profile security-review
nexus deploy --name my-agent --profile full-access

Profiles are stored in .nexus/profiles/ and can inherit from a base configuration.

Validating your configuration

Before deploying an agent with a new configuration, validate the YAML syntax and schema:

nexus config validate nexus.yaml

The validator checks: YAML syntax correctness, schema conformance against the Nexus configuration schema, tool name validity (all referenced tools exist in the registry), guardrail consistency (allowed_paths and allowed_hosts are syntactically valid), and memory configuration sanity (retention_days between 1 and 365). Invalid configurations produce specific error messages with line numbers and suggested fixes.

You can also view the agent configuration in a human-readable format:

nexus config show --agent my-agent

This shows the effective configuration after applying all profiles, environment variables, and defaults.

Tool configuration in depth

Each tool can be individually configured with options that control its behavior. Beyond the basic enable/disable, you can set: timeout ? maximum execution time per tool call (default: 60s, configurable per tool). max_retries ? number of retries on transient failure (default: 3). resource_limits ? CPU and memory limits for sandboxed tool execution. allowed_params ? restrict which parameters the agent can pass to the tool.

Example: configuring a custom tool with strict parameters:

tools:
  custom_deploy_tool:
    timeout: 300
    max_retries: 1
    allowed_params:
      - environment
      - version
      - config_file

Next steps

With a configured agent, you are ready to move beyond the CLI. Proceed to Step 4: SDK deep dive to learn how to integrate Nexus into your own applications.