Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opper.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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