# Configuration (/docs/guides/configuration)



Every wrapper is configured with a single JSON file, passed with `--config`. The same shape is shared across wrappers, with one backend-specific block (`copilot`, `claude`, `codex`, `opencode` or `antigravity`).

## Layering [#layering]

Settings resolve in this order, with later layers overriding earlier ones:

```
built-in defaults  ←  config file  ←  environment variables  ←  CLI flags
```

So a flag such as `--port 4000` beats `PORT=3000`, which beats `"port": 3010` in the file.

## Secrets and substitution [#secrets-and-substitution]

Never put credentials in `config.json`. Reference environment variables instead:

* `${VAR}` works anywhere inside a string, including in the middle of one.
* Bare `$VAR` works in some fields, for example MCP `args`.
* If a variable is not set, the token is left as-is so a misconfiguration stays visible rather than silently sending an empty value.

```json
{ "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" } }
```

## Shared blocks [#shared-blocks]

| Block       | Purpose                                                                            | Key fields                                               |
| ----------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `agentCard` | What the agent advertises. See [agent cards](/docs/concepts/agent-cards)           | `name`, `description`, `version`, `skills`, `streaming`  |
| `server`    | Networking                                                                         | `port`, `hostname`, `advertiseHost`, `advertiseProtocol` |
| `session`   | Multi-turn behaviour. See [sessions](/docs/concepts/sessions)                      | `reuseByContext`, `ttl`, `cleanupInterval`               |
| `features`  | Behaviour flags                                                                    | `streamArtifactChunks`, and per-wrapper event flags      |
| `events`    | Sideband events. See [observability](/docs/concepts/observability)                 | `enabled`, `transport`, `httpUrl`, `httpHeaders`         |
| `timeouts`  | Limits                                                                             | `prompt` (milliseconds)                                  |
| `logging`   | Logs                                                                               | `level`: `debug`, `info`, `warn`, `error`                |
| `mcp`       | Tool servers. See [MCP tools](/docs/guides/mcp-tools)                              | one entry per server                                     |
| `memory`    | Instructions and skills. See [memory and skills](/docs/concepts/memory-and-skills) | `instructions`, `skills`                                 |
| `subAgents` | Delegation. See [sub-agents](/docs/concepts/sub-agents)                            | `agents`, `options`                                      |

## Backend blocks [#backend-blocks]

| Wrapper           | Block         | Notable fields                                                                       |
| ----------------- | ------------- | ------------------------------------------------------------------------------------ |
| `a2a-copilot`     | `copilot`     | `model`, `systemPrompt`, `systemPromptMode`, `provider` (BYOK)                       |
| `a2a-claude`      | `claude`      | `workingDirectory`, `model`, `permissionMode`, `thinking`, `settingSources`          |
| `a2a-codex`       | `codex`       | `workingDirectory`, `model`, `sandboxMode`, `approvalPolicy`, `networkAccessEnabled` |
| `a2a-opencode`    | `opencode`    | `baseUrl`, `projectDirectory`, `model`, `agent`, `systemPromptMode`                  |
| `a2a-antigravity` | `antigravity` | `pythonPath`, auth mode, policies                                                    |

Full field tables are in each [package reference](/docs/reference/packages/core).

## Common environment variables and flags [#common-environment-variables-and-flags]

| Setting            | Flag                                           | Environment                                                                  |
| ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| Config file        | `--config <path>`                              | `CONFIG_FILE` (used by the `server.sh` scripts)                              |
| Port               | `--port`                                       | `PORT`                                                                       |
| Bind address       | `--hostname`                                   | `HOSTNAME`                                                                   |
| Advertised host    | `--advertise-host`                             | `ADVERTISE_HOST`                                                             |
| Workspace          | `--workspace`                                  | `WORKSPACE_DIR`                                                              |
| Model              | `--model`                                      | backend-specific, for example `COPILOT_MODEL`, `CLAUDE_MODEL`, `CODEX_MODEL` |
| Streamed artifacts | `--stream-artifacts` / `--no-stream-artifacts` | `STREAM_ARTIFACTS`                                                           |
| Log level          | `--log-level`                                  | `LOG_LEVEL`                                                                  |

Exact flags differ slightly between wrappers. Run `<wrapper> --help` or see the package reference.

## Start from an example [#start-from-an-example]

Each wrapper ships example agents under `agents/`. Copy one and edit it:

```bash
cp -r agents/example agents/my-agent
./agents/my-agent/start.sh start
```

The `start.sh` scripts support `start`, `stop`, `restart`, `status`, `logs` and `foreground`.