# Configuration reference

Look up the fields in facade.json, their defaults, and how Facade applies them.

## Top-level fields

Open the file through [Agent settings](https://facadecode.com/docs/settings/). It accepts JSON comments and trailing commas. An empty object uses the defaults.

| Field | Value | Default |
| --- | --- | --- |
| `yolo` | Boolean controlling CLI approvals and agent access. | `true` |
| `names` | List of nonblank suggested agent names. | Built-in name list |
| `clis` | Object containing built-in overrides and additional named entries. | `{}`; built-in CLIs remain available |
| `$schema` | String for editor schema metadata. | Omitted |

## CLI entry fields

| Field | Value | Default |
| --- | --- | --- |
| `type` | `claude`, `codex`, `agy`, `muse`, `opencode`, `pi`, or `custom`. | Implicit for exact built-in IDs; required for added entries. |
| `command` | One executable name or path. | Type’s command on PATH; required for custom. |
| `args` | Array of literal argument strings. | `[]` |
| `env` | Variable names mapped to strings or null. | `{}` |
| `model` | Nonblank model ID. | CLI decides. Not accepted for OpenCode or custom. |
| `effort` | Nonblank effort supported by the CLI and model. | CLI decides. Not accepted for OpenCode or custom. |
| `enabled` | Boolean controlling future starts and restoration. | `true` |
| `icon` | Built-in CLI ID or supported robot icon. | Type’s icon; `facade-pearl` for custom. |

Use the exact lowercase ID to configure a built-in entry, such as `codex`. A new entry must have a name distinct from every built-in ID and display name, even when capitalization is ignored. For example, use `Codex · work` rather than `Codex`. Added entries do not inherit settings from the built-in of their type.

`enabled: false` hides a valid entry and refuses future starts or restoration. It does not stop an agent already running.

## Environment values

```json
{
  "clis": {
    "codex": {
      "env": {
        "WORK_API_KEY": "${env:WORK_API_KEY}",
        "OLD_TOKEN": null
      }
    }
  }
}
```

- A string sets a variable. `null` removes it. An omitted variable is inherited.
- `${env:NAME}` reads the editor host’s environment. It does not read another key in the same object.
- A missing reference makes that entry unavailable. References expand once in `env` values, not in `args`.
- A literal value stays in facade.json. An environment reference keeps that value out of the file, but the CLI still receives the expanded value.

Setting a variable in an integrated terminal that is already open does not update the editor host’s environment. Make it available before starting the editor.

## Precedence and launch options

Facade first uses any model and effort specified for the new agent, then the entry’s defaults. If neither provides a value, the CLI decides. OpenCode keeps both choices in its own configuration.

For built-in types, use the dedicated fields for model and effort. Facade also sets permissions, conversation IDs, working folders, and its own tools. It rejects arguments that conflict with these choices or prevent an interactive session from starting.

Facade looks for facade.json in the Facade home: the **Facade: Home** VS Code setting if set, then `FACADE_HOME`, then `~/.facade`. Open Settings from the project to find its active file.

## File errors and entry errors

A file-level error, such as invalid JSON, a duplicate key, or an unknown top-level field, blocks new starts and restoration. An error inside one CLI entry makes only that entry unavailable. Running agents keep running.

Follow the error’s setting path and correct that value. Facade does not silently substitute old settings. See [Troubleshooting](https://facadecode.com/docs/troubleshooting/) for common startup and provider errors.