Skip to main content
The agents.yaml file is the central registry for all agents in Opperator. It defines how the daemon manages agents: what command to run, environment variables, restart behavior, and more. Location: ~/.config/opperator/agents.yaml The Builder agent automatically creates and updates entries in agents.yaml when you bootstrap a new agent. Manual editing is rarely necessary. The daemon automatically detects changes to this file and applies them in real-time - starting new agents, stopping removed agents, and restarting modified ones.

​
Configuration Examples

  • Minimal
  • Complete
  • Multiple Agents
The bare minimum needed to define an agent:
agents:
  - name: my_agent
    command: python3
    args:
      - agent.py
    process_root: agents/my_agent
This simple configuration is enough to get started. The agent will run on-demand when you interact with it.

​
Reference

​
name
string
required
Unique identifier for the agent. Used in CLI commands, slash commands, and the UI.Requirements:
  • Must be unique in agents.yaml
  • Lowercase with underscores
  • Descriptive (e.g., system_monitor, not agent1)
name: email_notifier
​
command
string
required
Path to the executable or command name.Options:
# Command in PATH
command: python3

# Relative to process_root
command: .venv/bin/python
​
args
string[]
default:"[]"
Command-line arguments passed to the executable.
args:
  - agent.py
  - --verbose
  - --config=/etc/agent/config.json
​
process_root
string
required
Working directory for the agent. Relative paths are resolved from ~/.config/opperator/.
process_root: agents/my_agent
# Resolves to: ~/.config/opperator/agents/my_agent
The agent’s Python virtual environment is expected at {process_root}/.venv/
​
description
string
Short description of what the agent does. Shown in the agent picker and included in the base system prompt. Keep it concise to reduce token usage.
description: Monitors system resources and sends alerts
​
color
string
Hex color code for the agent name displayed throughout the TUI.
color: "#3ccad7"
​
env
object
default:"{}"
Environment variables available to the agent process.
env:
  LOG_LEVEL: debug
  API_URL: https://api.example.com
  TIMEOUT: "30"
  ENABLE_WEBHOOKS: "true"
Important: All values must be strings. Wrap numbers and booleans in quotes.Never store secrets in env! Use the secret manager instead:
# In your agent code
api_key = self.get_secret("api_key")
​
auto_restart
boolean
default:"false"
Automatically restart the agent if it crashes. Useful for always-on services.
auto_restart: true
​
max_restarts
integer
default:"0"
Maximum number of restart attempts when the agent crashes. Use with auto_restart: true.
  • 0 = unlimited restarts
  • Only applies when auto_restart is enabled
auto_restart: true
max_restarts: 5
​
start_with_daemon
boolean
default:"false"
Automatically start this agent when the Opperator daemon starts. Use for monitoring agents, notification handlers, or services that should always be running.
start_with_daemon: true
​
system_prompt
string
Additional LLM instructions appended to the system prompt when this agent is selected. Multi-line strings are supported with |.
system_prompt: |
  You are a system monitoring agent.

  Capabilities:
  - Monitor CPU, memory, and disk usage
  - Send alerts when thresholds are exceeded
  - Generate performance reports

​
See also