Skip to main content

​
Config file location

Operator reads its configuration from ~/.operator/config.json on startup. If the file does not exist, Operator starts with built-in defaults so you can run operator onboard or edit the file manually.
Two environment variables control file locations:
  • OPERATOR_CONFIG — override the full path to the config file (e.g. OPERATOR_CONFIG=/etc/operator/config.json)
  • OPERATOR_HOME — override the base directory for workspace defaults. When set, the default workspace becomes $OPERATOR_HOME/workspace.

​
Top-level structure

The file is a single JSON object with these top-level keys: 
{
  "agents": {
    "defaults": { ... }
  },
  "model_list": [ ... ],
  "channels": {
    "telegram": { ... },
    "discord": { ... },
    "slack": { ... }
  },
  "tools": {
    "web": { ... },
    "exec": { ... },
    "mcp": { ... },
    "cron": { ... },
    "skills": { ... }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  },
  "devices": {
    "enabled": false,
    "monitor_usb": true
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  }
}
SectionPurpose
agentsDefault model, workspace, and runtime limits for all agents
model_listDeclare every AI model the agent can use, with credentials and routing
channelsMessaging integrations (Telegram, Discord, Slack, WhatsApp, and more)
toolsWeb search, shell execution, MCP servers, cron scheduling, and skills
heartbeatPeriodic health-check ping sent from the agent
devicesUSB device monitoring and hardware integration
gatewayLocal HTTP gateway host and port

​
Environment variable overrides

Every field in config.json has a corresponding environment variable. The pattern is: 
OPERATOR_<SECTION>_<KEY>
Nested keys use underscores as separators. Environment variables are applied after the file is loaded, so they always win. 
# Override the default model
OPERATOR_AGENTS_DEFAULTS_MODEL_NAME=claude-sonnet-4.6

# Enable deny patterns for shell execution
OPERATOR_TOOLS_EXEC_ENABLE_DENY_PATTERNS=true

# Change the gateway port
OPERATOR_GATEWAY_PORT=18791

# Override the workspace path
OPERATOR_AGENTS_DEFAULTS_WORKSPACE=/home/user/myworkspace
Environment variables are useful in containers or CI environments where you don’t want to write a config file to disk. Map secrets as environment variables rather than storing API keys in the JSON file.

​
Complete example

The following is an abridged version of the full example configuration shipped with Operator: 
{
  "agents": {
    "defaults": {
      "workspace": "~/.operator/workspace",
      "restrict_to_workspace": true,
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-your-key",
      "api_base": "https://api.anthropic.com/v1"
    },
    {
      "model_name": "gemini",
      "model": "antigravity/gemini-2.0-flash",
      "auth_method": "oauth"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allow_from": ["YOUR_TELEGRAM_USER_ID"]
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "allow_from": []
    }
  },
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": []
    },
    "web": {
      "duckduckgo": { "enabled": true, "max_results": 5 }
    }
  },
  "heartbeat": { "enabled": true, "interval": 30 },
  "gateway": { "host": "127.0.0.1", "port": 18790 }
}

​
Next steps

AI model configuration

Add providers, set API keys, and configure multi-model load balancing.

Agent configuration

Set workspace paths, token limits, temperature, and tool iteration caps.

Security & sandboxing

Restrict workspaces, block dangerous shell commands, and limit channel access.

Build docs developers (and LLMs) love

Get started for freeTalk to us