Where configuration lives¶
There are two ways codeably gets its configuration, and which one you're in decides everything else on these pages.
Run it as a server, so docker-compose or Kubernetes or anything else long-lived, and the database is the store of record. You edit it in the Configuration studio in the dashboard, and the server picks the change up while it runs. Run it as the CLI, one shot at a time, and it reads agentsmith.yml from disk, the whole file.
Why not the file for the server too? Because on Kubernetes the file is a mounted ConfigMap, mounted ConfigMaps are read only, and a studio save against one would be a no-op. So the database holds the configuration, and the file keeps the one job only a file can do. If you've been copying config blocks into a mounted ConfigMap and wondering why nothing happened, this page is the answer.
What a server reads from the file¶
At boot the server reads the bootstrap slice out of agentsmith.yml:
persistence:
provider: sqlite # sqlite | postgresql | mysql | sqlserver
connection_string: "Data Source=/var/lib/agentsmith/agentsmith.db"
secrets:
anthropic_api_key: ${ANTHROPIC_API_KEY}
github_token: ${GITHUB_TOKEN}
It's a chicken and egg thing. The connection to the database can't live in the database it describes, and the names of your secret environment variables have to be known before anything else loads. The optional auth: block (the token authority for dashboard sign-in) is read from the file for the same reason. Everything else (agents, trackers, connections, repos, projects, MCP servers, and the global settings groups) comes out of the database.
The database connection can also come from the environment instead of the file. Set both AGENTSMITH_PERSISTENCE_PROVIDER and AGENTSMITH_PERSISTENCE_CONNECTION and they replace the whole persistence: block; agentsmith.yml has the details and the one trap.
So a server that boots with a full agentsmith.yml mounted at /app/config/agentsmith.yml will use the bootstrap slice and ignore the rest. The file isn't validated against what's in the database, and nothing warns you that the projects: block you just edited is inert. Put the catalog into the database instead, one of the two ways below.
Getting an existing YAML into the database¶
If you already have a working agentsmith.yml, import it. Once:
The import is guarded. It refuses to run against a store that already has content unless you pass --force, so the destructive version is one you type on purpose. persistence: is deliberately excluded from the import, since it stays in the file where the bootstrap can find it. An import that carries two spellings of one name (TodoList and todolist as two projects, say) is refused as a whole and names both; see names are case-insensitive.
The studio has the same thing as a button (Import agentsmith.yml, top of every catalog page), and the other direction too, Export agentsmith.yml, or from the command line:
Export gives you back a file that round-trips through the real loader, which makes it a backup, a code review artifact, and the thing you hand to a second environment. Secrets come out as env var names, never values.
Every edit is attributed and revertible¶
The studio writes a change record for each edit: who, when, which fields, old value to new value. The Changes view lists them newest first, and each one has a revert button.
A row written by agent-smith config import says by cli-import; edits from the studio carry the person, and changes the admin assistant applied carry the person and the run.
A config write also bumps a counter in Redis, and the running server watches it. Change a tracker's polling interval and the poller picks it up on its next cycle, with no restart in the loop. The exceptions are the bootstrap slice (change persistence: and you're restarting the process, by definition) and the handful of settings the Settings page marks as read at startup.
Which surface owns which block¶
| Block | Server (docker / k8s) | CLI |
|---|---|---|
persistence: |
the file (or the two env vars), read at boot | unused |
secrets: auth: |
the file, read at boot | the file |
agents: trackers: connections: repos: projects: mcp_servers: design_sources: |
database, via the Config studio | the file |
deployment: sandbox: orchestrator: queue: limits: skills: dialogue: registries: primary_provider: pipeline_cost_cap: pipeline_data_flow: spec_review: series: trace: |
database, via Settings | the file |
pipeline_triggers: |
database, with no studio page, so import or export to edit it | the file |
tool_runner: |
config/agentsmith.yml under the working directory |
the same |
The last two rows are the exceptions. pipeline_triggers: is stored and served like everything else but has no catalog screen, so you edit it by exporting, changing the block, and importing with --force. tool_runner: (how the api-scan tools are started, see Tool configuration) is read straight from the file in both modes.
Next¶
- The Config studio, the catalogs, the project drawer, and what the studio refuses to let you save.
- Project templates, building one project's contexts after another project's.
- Deployment templates, how a context is delivered: its files, environments and promotion.
- Settings, the fourteen global groups and what each one actually changes.
- Design sources, giving a project read access to its Figma designs.
- agentsmith.yml, the file itself: bootstrap, CLI, import/export, schema.