Configuration
Each page in this section lists the fields, defaults, and JSON examples for one area. For first-time setup, read Getting started. For what a feature does and when to reach for it, start from its feature page and come back here for the exact fields.
Configuration files
DotCraft reads global ~/.craft/config.json first, then overlays workspace .craft/config.json. Workspace fields win. String values support $VAR and ${VAR} environment variable placeholders. An unset variable keeps its placeholder unchanged.
Some settings have a file of their own in the same two places: global under ~/.craft/, workspace under .craft/, with the workspace winning.
| File | Holds | Reference |
|---|---|---|
config.json | Most settings | The pages in this section |
hooks.json | Lifecycle hooks | Hooks |
models.json | Model context windows and Fast Mode support | Models and providers |
model-thinking-adapters.json | Reasoning request shapes | Models and providers |
plugin-config.json | Settings that plugins declare | Plugins, MCP, and LSP |
commands/ | Custom / commands | Conversations |
<channel>.json | Channel adapters, workspace only | Channels |
For when a changed setting takes effect, see Settings lifecycle.
Inspect configuration from the CLI
dotcraft config schema prints the sections and fields included in the configuration schema, with their types, defaults, sensitivity, and reload behavior. dotcraft config show prints the merged configuration of one workspace with ApiKey, Password, and Token values masked as ***.
dotcraft config schema --section Tools.Web
dotcraft config schema --json
dotcraft config show --json--section accepts a section's display name or its JSON path. --json writes machine-readable output, and config show is indented JSON either way. config show reads the workspace in the current directory; pass --workspace for another one.
Change configuration from a client
AppServer clients change settings by key path instead of editing files. config/read returns the effective configuration with sensitive values masked, and can include the user and workspace layers. config/value/write changes one key path, such as Tools.CodeMode.Mode, and config/batchWrite applies several edits to one layer at once. A write targets the workspace layer unless it names the user layer's file. Credentials are not written this way; the provider methods own them. The AppServer protocol lists the parameters and error codes.
The server validates a write before saving it: the result must still load as a configuration, and every changed field must satisfy its type, range, and allowed values. A rejected write leaves the file untouched. An accepted write updates the running AppServer according to each field's reload behavior and is announced through config/changed with the changed key paths.
The Dashboard Settings page saves a whole layer file through the same path, so its saves are validated, applied, and announced the same way. A masked *** value in a saved document keeps the stored secret.