Configuration

Full reference for the MeepaGateway config file.

MeepaGateway uses a YAML config file. The default location is ~/.meepagateway/config.yaml. Specify a custom path with --config:

meepagateway --config /path/to/config.yaml start

If no config file exists on first run, the gateway enters setup mode.

File format

The config is YAML. Top-level sections:

providers:        # LLM providers and routing
cron:             # Cron scheduler settings
captain:          # Captain Dashboard settings
hooks:            # Inbound webhook configuration
agents:           # List of agent definitions

---

providers

providers:
  primary: anthropic
  fallback:
    - openai
  health_check_interval: 30s
  providers:
    anthropic:
      api_key_env: ANTHROPIC_API_KEY
      model: claude-opus-4-6
    openai:
      api_key_env: OPENAI_API_KEY
      model: gpt-4o
      base_url: https://api.openai.com/v1  # optional
      max_tokens: 8192                     # optional

Field	Type	Required	Description
primary	string	yes	Name of the primary provider. Must match a key under providers.providers.
fallback	list	no	Ordered list of fallback provider names tried when primary is unhealthy.
health_check_interval	duration	yes	How often to poll provider health (e.g. 30s, 5m).

Per-provider fields (under providers.providers.<name>):

Field	Type	Required	Description
api_key_env	string	yes	Environment variable holding the API key.
model	string	yes	Default model for this provider.
base_url	string	no	Override the provider’s API base URL. Useful for proxies or OpenAI-compatible endpoints.
max_tokens	integer	no	Maximum tokens per response.

---

captain

captain:
  enabled: true
  bind: 127.0.0.1
  port: 63372
  exposure: local
  password_hash: "$argon2..."      # set via setup wizard
  api_keys: []                     # managed by the gateway, not hand-edited
  webauthn_credentials: []         # managed by the gateway
  public_url: ""                   # for cloudflare_tunnel / reverse_proxy modes
  cloudflare_token: ""             # for cloudflare_tunnel mode

Field	Type	Default	Description
enabled	bool	true	Enable the Captain Dashboard.
bind	string	127.0.0.1	IP address to bind the dashboard listener.
port	integer	63372	Port for the dashboard.
exposure	string	local	How the dashboard is exposed. See below.
password_hash	string	—	Argon2-hashed password. Set via setup wizard, not by hand.
public_url	string	—	Public URL (for cloudflare_tunnel or reverse_proxy exposure).
cloudflare_token	string	—	Cloudflare tunnel token (for cloudflare_tunnel exposure).

Exposure modes:

Value	Behavior
local	Bind 127.0.0.1 — localhost only (default)
lan	Bind 0.0.0.0 — local network
tailscale_private	Bind 127.0.0.1, tailscale serve proxies
cloudflare_tunnel	Bind 127.0.0.1, Cloudflare tunnel routes to captain port
tailscale_funnel	Bind 0.0.0.0, Tailscale Funnel
reverse_proxy	Bind 0.0.0.0, user-managed reverse proxy

---

cron

cron:
  enabled: true
  max_concurrent_runs: 3

Field	Type	Default	Description
enabled	bool	true	Enable the cron subsystem.
max_concurrent_runs	integer	3	Maximum concurrent cron jobs across all agents.

Cron jobs are defined per-agent under agents[].cron_jobs. See Cron.

---

agents

Each item in the agents list defines one agent. All configuration fields are set directly on the agent.

agents:
  - id: meepa
    name: Meepa
    default: true
    provider: null
    model: null
    max_iterations: 10
    max_tool_failures: 3
    image_config:
      enabled: false
      base_image: ghcr.io/bogpad/meepagateway-sandbox:latest
      packages: []
      env_vars: {}
      inject_credentials_env: true
      inject_secrets_env: true
      redact_secrets: true
    tools: null
    file_access:
      unrestricted: true
      allow_read: []
      allow_read_write: []
      deny: []
      allow_home_dotfiles: false
      allow_network: true
    container_mode:
      enabled: true
      image: ''
      memory_limit: 512m
      timeout_seconds: 300
      network: bridge
    connectors:
      - name: meepachat
        type: meepachat
        webhook: false
        bot_token: ${sops:meepachat.bot_token}
        url: https://chat.meepachat.ai
    cron_jobs: []

Field	Type	Required	Description
id	string	yes	Unique identifier. Used in API paths and logs.
name	string	yes	Display name.
default	bool	no	Mark as the default agent. Exactly one agent must be default.
provider	string	no	LLM provider to use. Defaults to providers.primary.
model	string	no	Model override for this agent.
max_iterations	integer	no	Maximum agent loop iterations per message. Default: 10.
max_tool_failures	integer	no	Maximum consecutive failures before the agent is nudged. Default: 3.

Agent workspace is auto-derived from the ID: ~/.meepagateway/agents/{id}/. Files in the workspace (SOUL.md, MEMORY.md, USER.md, memory.db, skills/, .mcp.json) are not configured here.

file_access

Controls which paths the file tools can read or write.

file_access:
  unrestricted: true        # if true, all other fields are ignored
  allow_read: []            # paths allowed for read-only access
  allow_read_write: []      # paths allowed for read+write access
  deny: []                  # paths explicitly denied
  allow_home_dotfiles: false
  allow_network: true

Field	Type	Default	Description
unrestricted	bool	true	Allow access to all paths. When true, other fields are ignored.
allow_read	list	[]	Paths the agent may read.
allow_read_write	list	[]	Paths the agent may read and write.
deny	list	[]	Paths explicitly blocked. Takes precedence over allow lists.
allow_home_dotfiles	bool	false	Allow reading dotfiles in the home directory.
allow_network	bool	true	Allow network access from tools.

image_config

Configuration for the sandbox image used in container mode.

image_config:
  enabled: false
  base_image: ghcr.io/bogpad/meepagateway-sandbox:latest
  packages: []
  env_vars: {}
  inject_credentials_env: true
  inject_secrets_env: true
  redact_secrets: true

Field	Type	Default	Description
enabled	bool	false	Enable image-based sandboxing.
base_image	string	—	OCI image to use as the sandbox base.
packages	list	[]	Extra packages to install in the image.
env_vars	map	{}	Environment variables to inject into the container.
inject_credentials_env	bool	true	Inject provider credential env vars.
inject_secrets_env	bool	true	Inject SOPS-managed secrets as env vars.
redact_secrets	bool	true	Redact secret values from logs.

container_mode

Runtime settings for the container execution environment.

container_mode:
  enabled: true
  image: ''
  memory_limit: 512m
  timeout_seconds: 300
  network: bridge

Field	Type	Default	Description
enabled	bool	false	Run agent tools inside a container.
image	string	''	Override the container image (empty uses image_config.base_image).
memory_limit	string	512m	Memory limit for the container.
timeout_seconds	integer	300	Maximum seconds a container run may take.
network	string	bridge	Docker network mode.

See Isolation for full details.

Connectors

Connectors are flat objects — all fields are directly on the connector, not nested under a type key.

connectors:
  - name: meepachat
    type: meepachat
    webhook: false
    bot_token: BOT_ID.SECRET
    url: https://chat.example.com

  - name: discord-bot
    type: discord
    webhook: false
    bot_token: "Bot.Token..."
    guild_ids: []               # optional: restrict to specific guilds

  - name: telegram-bot
    type: telegram
    webhook: false
    bot_token: "1234567890:AAF..."
    poll_interval: 1s           # polling interval (or use webhook_url)
    webhook_url: ""             # optional: use webhook instead of polling
    webhook_port: null          # local port for webhook listener

  - name: slack-bot
    type: slack
    webhook: false
    bot_token: "xoxb-..."       # bot OAuth token
    app_token: "xapp-..."       # app-level token for Socket Mode

  - name: whatsapp-bot
    type: whatsapp
    webhook: false
    access_token: "..."         # WhatsApp Cloud API access token
    phone_number_id: "..."      # phone number ID from Meta dashboard
    verify_token: "..."         # webhook verification token
    webhook_port: 8444          # local port for webhook listener

Set webhook: true on any connector to use the centralized webhook system instead of per-connector polling or WebSocket.

Cron jobs

cron_jobs:
  - name: daily-digest
    enabled: true
    message: "Post the daily digest to the team channel"
    schedule:
      every: 24h          # interval schedule

  - name: weekday-standup
    enabled: true
    message: "Run the standup summary"
    schedule:
      cron: "0 0 9 * * 1-5 *"  # 7-field cron expression

  - name: one-time-reminder
    enabled: true
    message: "Send the project deadline reminder"
    schedule:
      at: "2026-12-31T09:00:00Z"  # one-shot

Tool filtering

tools:
  allow:
    - shell
    - read_file
    - write_file
  # deny:
  #   - shell

allow is an allowlist — only listed tools are available. deny removes specific tools. The two are mutually exclusive.

---

MCP servers

MCP servers are not configured in the main config file. Each agent has a .mcp.json file at ~/.meepagateway/agents/{id}/.mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-server": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Edit with: meepagateway agent mcp <id>

---

Environment variables

Variable	Description
ANTHROPIC_API_KEY	API key for the Anthropic provider
OPENAI_API_KEY	API key for the OpenAI provider
MEEPA_URL	Default gateway URL for CLI management commands
MEEPA_API_KEY	API key for CLI authentication
RUST_LOG	Log level (e.g. info, debug, meepa_gateway=debug)

Never put secrets directly in the config file. Reference them via api_key_env pointing to an environment variable.

---

Complete example

providers:
  primary: anthropic
  fallback:
    - openai
  health_check_interval: 30s
  providers:
    anthropic:
      api_key_env: ANTHROPIC_API_KEY
      model: claude-opus-4-6
    openai:
      api_key_env: OPENAI_API_KEY
      model: gpt-4o

cron:
  enabled: true
  max_concurrent_runs: 3

captain:
  enabled: true
  bind: 127.0.0.1
  port: 63372

agents:
  - id: meepa
    name: Meepa
    default: true
    max_iterations: 10
    max_tool_failures: 3
    file_access:
      unrestricted: true
      allow_network: true
    container_mode:
      enabled: false
    connectors:
      - name: meepachat
        type: meepachat
        webhook: false
        bot_token: ${sops:meepachat.bot_token}
        url: https://chat.example.com

  - id: coder
    name: Code Helper
    model: claude-opus-4-6
    max_iterations: 20
    file_access:
      unrestricted: false
      allow_read_write:
        - /home/user/projects
    tools:
      allow:
        - shell
        - read_file
        - write_file
    connectors:
      - name: discord-bot
        type: discord
        webhook: false
        bot_token: "Bot.Token..."
    cron_jobs:
      - name: daily-summary
        enabled: true
        message: "Summarize today's code changes"
        schedule:
          every: 24h