agnes-operator

name

agnes-operator

description

How to configure and customize THIS Agnes instance — the init prompt, the analyst workspace, branding / instance.yaml, and connectors — across its environments. Use when an operator or admin asks where the instance's content/config lives, how to change the init prompt or landing page, how to rebrand, or how a config value resolves. Triggers on "change the init prompt", "edit branding", "where does the config live", "how do I customize this instance", "change /home content", "initial workspace template".

Configuring this Agnes instance

Use this when someone wants to change an Agnes instance's content or configuration. The customizable surface spans a few independent layers; identify the layer first, and read the instance's live state instead of guessing.

Always start: read this instance's live config surface

Do NOT hardcode or assume where things live — every instance is registered differently. Read the actual state first:

agnes admin config-surface --json

It returns, for THIS instance: every config knob with its resolved value and source (env / yaml / default), the registered Initial Workspace Template repo URL + branch, the registered marketplaces, and infra_repo_url. Use those concrete values in your answer. (Same data via GET /api/admin/config-surface or the admin_config_surface MCP tool.)

Layer 1 — Init prompt & analyst workspace (Initial Workspace Template)

The init prompt shown on /home and the workspace an analyst receives from agnes init come from the registered Initial Workspace Template (IWT) seed repo — its URL is in the config surface above.

• Init prompt = install-prompt/template.md.tmpl in that repo.
• Analyst workspace = the workspace/ subtree in that repo (only workspace/ ships to analysts).

To change either: edit the file in the seed repo, then click Sync now under /admin/server-config → Initial Workspace Template (the deploy is per-instance and manual — merging the repo alone does nothing). When no IWT is registered, a bundled snapshot inside the wheel is used instead.

Gotcha: when the seed repo owns the template, the /admin/agent-prompt editor is read-only and saving there returns 409 iwt_seed_owns_template. Edit the repo file + Sync now; never the admin textbox.

See docs/initial-workspace-override.md and docs/seed-repo-contract.md.

Layer 2 — Branding, theme, landing route, data source (instance.yaml)

These are config knobs (name, subtitle, brand, theme, home_route, data source, …). Each resolves env var > instance.yaml > built-in default — the source column in the config surface tells you which tier is currently winning.

Footgun: the env tier shadows the YAML tier. If a knob is pinned via an AGNES_* env var, changing it in /admin/server-config (which writes YAML) does nothing. Pin via env or manage via the admin UI, not both.

The full knob reference — env var ↔ instance.yaml path ↔ default for every resolver — is docs/CONFIGURATION.md.

Layer 3 — Connectors & marketplaces

Registered marketplaces (curated content served to users) are listed in the config surface. Connector pre-provisioning (shared OAuth clients, base URLs) are config knobs in Layer 2.

Where the app vs the infra lives

• The app (the /home page, routes, the agnes binary) is the Agnes product itself — change its behavior in the application codebase, shipped as a new image.
• The infrastructure that provisions this instance is NOT tracked by the app unless an operator set infra_repo_url (shown in the config surface). If it's empty, the instance does not know its provisioning repo — ask the operator or check the deployment.

Rule of thumb

Content (init prompt, workspace) → IWT seed repo + Sync now (easy). Branding / config → instance.yaml knobs (mind the env-shadows-yaml footgun). Always read the live config surface first so your answer names this instance's real pointers.