Configuration
How a2a-wrapper configuration works. The JSON config file, the layering order of defaults, file, environment variables and CLI flags, environment-variable substitution, and the blocks every wrapper shares.
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
Settings resolve in this order, with later layers overriding earlier ones:
built-in defaults ← config file ← environment variables ← CLI flagsSo a flag such as --port 4000 beats PORT=3000, which beats "port": 3010 in the file.
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
$VARworks in some fields, for example MCPargs. - If a variable is not set, the token is left as-is so a misconfiguration stays visible rather than silently sending an empty value.
{ "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" } }Shared blocks
| Block | Purpose | Key fields |
|---|---|---|
agentCard | What the agent advertises. See agent cards | name, description, version, skills, streaming |
server | Networking | port, hostname, advertiseHost, advertiseProtocol |
session | Multi-turn behaviour. See sessions | reuseByContext, ttl, cleanupInterval |
features | Behaviour flags | streamArtifactChunks, and per-wrapper event flags |
events | Sideband events. See observability | enabled, transport, httpUrl, httpHeaders |
timeouts | Limits | prompt (milliseconds) |
logging | Logs | level: debug, info, warn, error |
mcp | Tool servers. See MCP tools | one entry per server |
memory | Instructions and skills. See memory and skills | instructions, skills |
subAgents | Delegation. See sub-agents | agents, options |
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.
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
Each wrapper ships example agents under agents/. Copy one and edit it:
cp -r agents/example agents/my-agent
./agents/my-agent/start.sh startThe start.sh scripts support start, stop, restart, status, logs and foreground.
Choosing a wrapper
Compare a2a-copilot, a2a-claude, a2a-codex, a2a-opencode and a2a-antigravity. Backends, provider flexibility, sandboxing, streaming, and default ports, so you can pick the right A2A wrapper for your agent.
MCP tool servers
Give an a2a-wrapper agent extra tools through MCP. Stdio and HTTP server configuration for each wrapper, authenticated remote servers with environment-variable headers, and OAuth.