Configuration#

ID Agents is configured through environment variables and YAML deployment files. Environment variables control global settings like database connections and API keys. YAML files define teams, agents, and their capabilities.

Environment Variables#

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`ANTHROPIC_API_KEY`	No	Anthropic API key (not needed with Claude Max -- run `claude login` instead)
`CLAUDE_MODEL`	No	Default model (e.g., `claude-opus-4-6`)
`ORCHESTRATOR_TYPE`	No	Default agent runtime type
`ID_PROJECT`	No	Default team/project name
`ID_REGISTRAR_PRIVATE_KEY`	No	Wallet private key for onchain agent registration
`ID_CONTROL_API_KEY`	No	API key for the `/remote` endpoint
`ID_AGENT_API_KEY`	No	Default API key for agent authentication
`PUBLIC_BASE_URL`	No	Public URL base for agents (e.g., `https://idbot.live`)
`MANAGER_PORT`	No	Manager port (default: 4100)

Set these in a .env file at the project root or export them in your shell environment. Environment variables take precedence over config file values.

YAML Configuration#

Deploy multiple agents from a single YAML config file. Use /deploy path/to/config.yaml from the CLI.

Minimal Example#

version: "1.0"
team: my-team

agents:
  - name: coder
    description: "Writes and reviews code"
  - name: researcher
    description: "Research and analysis"

Full Example#

version: "1.0"
team: production-team

parameters:
  - name: model_tier
    default: sonnet

onchain:
  chainId: 11155111
  registryAddress: "0x1234567890abcdef1234567890abcdef12345678"
  registrarAddress: "0xabcdef1234567890abcdef1234567890abcdef12"
  register: false

defaults:
  runtime: claude-code
  model: claude-haiku-4-5-20251001
  requireAuth: true
  plugins:
    - name: id-rest-ap
      path: plugins/id-rest-ap

agents:
  - name: lead
    model: claude-${model_tier}-4-20250514
    systemPrompt: |
      You are the lead developer.
      Coordinate work and review code from other agents.
    register: true

  - name: dev-frontend
    systemPrompt: "You specialize in React and TypeScript."

  - name: dev-backend
    systemPrompt: "You specialize in Node.js and databases."

  - name: public-assistant
    requireAuth: false
    systemPrompt: "You are a helpful public assistant."

Top-Level Fields#

version#

Required. Configuration format version. Currently "1.0".

team#

Team or namespace for the deployment. Defaults to default.

parameters#

Define substitution variables using ${name} syntax throughout the config:

parameters:
  - name: environment
    default: development
  - name: model_tier
    default: haiku

team: project-${environment}

agents:
  - name: worker-${environment}
    model: claude-${model_tier}-4-5-20251001

Each parameter accepts name (required), default, and description fields.

onchain#

Configuration for onchain agent registration:

Field	Required	Description
`chainId`	Yes	EVM chain ID (e.g., 11155111 for Sepolia)
`registryAddress`	Yes	Agent registry contract address
`registrarAddress`	No	Registrar contract address
`register`	No	Default registration setting for all agents

defaults#

Default settings applied to all agents unless overridden at the agent level:

Field	Type	Description
`runtime`	String	Default runtime (`claude-code`)
`model`	String	Default LLM model
`requireAuth`	Boolean	Require API key authentication
`plugins`	Array	Default plugins for Claude Code agents
`skills`	Array	Default skills
`allowedTools`	Array	Default tool restrictions

Agent Configuration#

Each agent in the agents array supports these fields:

Field	Required	Default	Description
`name`	Yes	--	Agent name (unique within team)
`description`	No	--	Human-readable description
`model`	No	From defaults	LLM model to use
`runtime`	No	From defaults	Agent runtime
`systemPrompt`	No	--	Custom system prompt
`apiKey`	No	--	Static API key (legacy)
`requireAuth`	No	From defaults	Require client authentication
`plugins`	No	From defaults	Plugins for Claude Code agents
`skills`	No	From defaults	Skills
`allowedTools`	No	From defaults	Restrict available tools
`env`	No	`{}`	Environment variables for the process
`register`	No	From onchain	Register agent onchain
`domain`	No	--	ENS domain (preserved across redeploys)
`tokenId`	No	--	Namehash of the ENS domain
`workingDirectory`	No	--	Working directory for the agent

Agent Authentication#

Manager-Issued Keys (Recommended)#

Set requireAuth: true to require clients to authenticate with manager-issued API keys:

# Issue a client key
curl -X POST http://localhost:4100/keys/issue \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ID_CONTROL_API_KEY" \
  -d '{"name": "my-client", "scopes": ["talk"]}'

# Use the key
curl http://localhost:4101/talk \
  -H "X-API-Key: sk-id-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'

Public endpoints (/health, /.well-known/restap.json) are always accessible without authentication.

plugins:
  - name: id-rest-ap
    path: plugins/id-rest-ap

Environment Variable References#

Use ${env:VAR_NAME} syntax to reference environment variables in config files, keeping secrets out of YAML:

defaults:
  apiKey: ${env:ID_AGENT_API_KEY}

Config File Locations#

ID Agents looks for configuration files in this order:

Path specified via CLI: /deploy path/to/config.yaml
Team config: configs/<team-name>.yaml
Default config: configs/default.yaml

Configuration