Configuration
Configuration is JSON, in at most two files you'll ever edit:
shipped defaults
↓ merged under
~/.config/podcode/config.json global — everything you run
↓ merged under
<workspace>/.podcode/config.json project — this repository onlyLater layers win for scalar values. Arrays concatenate rather than replace — that is the one merge rule worth memorising, because it is the source of the most common configuration surprise: a harness declared in both layers arrives with its chain doubled. Declare each chain in exactly one layer.
The keys
Every capability in these docs is one of these:
| Key | What it configures | Page |
|---|---|---|
agent | Custom agents, and overrides on built-in ones | Agents |
harness | Named agent chains | Harnesses |
permission | Project-wide permission rules | Permissions |
memory | The embedder and retrieval settings | Memory |
provider | Per-provider settings and model registry patches | Providers |
plugin, plugin_config | Plugin registration | Plugins |
command | Slash-command templates | |
instructions | Extra files folded into the system prompt |
The workspace trust boundary
.podcode/config.json ships inside the repository. For a repository you just cloned, that file is written by whoever wrote the repository — so the keys that grant code execution, redirect credentials, or claim operator identity are stripped from the project layer before it merges, and are honoured only from your own global config:
plugin, plugin_autodiscover, plugin_config, agent, agent_autodiscover, operator_uid, and — inside provider — api_key, base_url, env, and npm.
Two dual-use keys are kept but reduced: slash-command templates from a project keep their text with inline shell expansion disarmed, and provider keeps its models registry patches while losing the four sub-keys above.
Editing
Podcode reads config at server start and caches it per workspace. Settings writes are applied live; hand-edits to config.json want a restart:
podcodeA malformed config is not silently half-applied — if the merged result fails validation, the shipped defaults are used and the reason is written to the log.