Using an overlay

Use an overlay when your deployment needs organization-specific tools, workflows, skills, personas, prompts, or sandbox files without turning the base Centaur repo into a fork.

An overlay is a separate Git repo listed in Helm values under overlays.sources. The repo-cache DaemonSet checks out each repo on every node; the API pod reads those checkouts from /var/lib/centaur/repos, and sandbox pods read the same revisions from /home/agent/github.

Later overlay sources shadow earlier ones when a tool, workflow, or skill name collides. This lets the base Centaur repo stay generic while each deployment layers in reviewed organization behavior.

Overlay layout

centaur-overlay/
├── tools/
│   └── warehouse/
│       ├── client.py
│       └── pyproject.toml
├── workflows/
│   └── nightly_report.py
├── .agents/
│   └── skills/
│       └── incident-response/
│           └── SKILL.md
└── services/
    └── sandbox/
        └── SYSTEM_PROMPT.md

Only include the directories your deployment needs.

Configure ordered sources

Declare every repo that contributes runtime extension points:

overlays:
  sources:
    - repo: paradigmxyz/centaur
      ref: 5da358a2
 
    - repo: your-org/centaur-overlay
      ref: abc1234

repo is owner/name on GitHub. ref can be a branch, tag, or commit SHA; pinning a SHA is recommended for production.

Each source defaults to the conventional layout — toolsSubdir: tools, workflowsSubdir: workflows, skillsSubdir: .agents/skills — and directories a repo does not contain are skipped at runtime, so a skills-only overlay needs no extra configuration. Set a subdir to a non-default path to relocate it, or to "" to explicitly disable that surface for a source:

    - repo: your-org/workflows-only
      ref: def5678
      workflowsSubdir: flows
      toolsSubdir: ""
      skillsSubdir: ""

For compatibility, when overlays.sources is empty the chart maps toolServer.repo, toolServer.ref, toolServer.subdir, and toolServer.extraSources[] into the same ordered overlay list.

Mount paths

Repo-cache-backed overlays appear under different prefixes depending on where you are debugging:

Do not use the sandbox path when debugging API discovery. If a tool or workflow is missing from API discovery, inspect /var/lib/centaur/repos/... in the API container. If a skill or workflow-host import is missing, inspect /home/agent/github/... in the sandbox.

Discovery paths

The chart renders API discovery paths from the ordered overlay list:

TOOL_DIRS=/var/lib/centaur/repos/paradigmxyz/centaur/tools:/var/lib/centaur/repos/your-org/centaur-overlay/tools
WORKFLOW_DIRS=/var/lib/centaur/repos/paradigmxyz/centaur/workflows:/var/lib/centaur/repos/your-org/centaur-overlay/workflows

The same ordered workflow list is translated for workflow-host sandboxes:

WORKFLOW_DIRS=/home/agent/github/paradigmxyz/centaur/workflows:/home/agent/github/your-org/centaur-overlay/workflows

Agent sandboxes receive overlay skills through:

CENTAUR_SKILL_DIRS=/home/agent/github/paradigmxyz/centaur/.agents/skills:/home/agent/github/your-org/centaur-overlay/.agents/skills

The sandbox entrypoint copies each existing directory from CENTAUR_SKILL_DIRS into the agent workspace in order, so later overlay skill directories can replace earlier skill names.

Prompt overlays

For small prompt additions, keep using the chart-level escape hatch:

overlay:
  systemPrompt: |
    Add deployment-specific agent guidance here.

For larger prompt/persona sets, keep files in an overlay repo and expose their paths through overlays.sources as that surface is wired into your deployment. Do not rely on overlay.image.*; repo-cache-backed overlays are the default delivery path.

Verify the overlay

Verify the API pod sees the ordered API-side paths:

kubectl exec -n centaur deploy/centaur-centaur-api-rs -- sh -lc '
  echo "$TOOL_DIRS"
  echo "$WORKFLOW_DIRS"
  for d in ${TOOL_DIRS//:/ }; do test -d "$d" && find "$d" -maxdepth 1 -mindepth 1 -type d | sort; done
  for d in ${WORKFLOW_DIRS//:/ }; do test -d "$d" && find "$d" -maxdepth 1 -name "*.py" | sort; done
'

Verify an agent sandbox sees merged tools and copied skills:

kubectl exec -n centaur <agent-sandbox-pod> -- sh -lc '
  echo "$TOOL_DIRS"
  echo "$CENTAUR_SKILL_DIRS"
  ls -la /app/tools
  find /workspace/.agents/skills -maxdepth 2 -type f -name SKILL.md | sort
'

Verify a workflow-host sandbox sees the sandbox-translated workflow list:

kubectl exec -n centaur <workflow-host-pod> -- sh -lc '
  echo "$WORKFLOW_DIRS"
  for d in ${WORKFLOW_DIRS//:/ }; do test -d "$d" && find "$d" -maxdepth 1 -name "*.py" | sort; done
'

If something is missing, check the configured repo/ref, repo-cache readiness, the rendered env vars, and the API or sandbox mount prefix relevant to the extension type.