Configuration

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

Getting Started

Configuration

Connectors

Agents

Infrastructure

Deployment

Configuration

File format

`providers`

`captain`

`cron`

`agents`

`file_access`

`image_config`

`container_mode`

Connectors

Cron jobs

Tool filtering

MCP servers

Environment variables

Complete example

Getting Started

Configuration

Connectors

Agents

Infrastructure

Deployment

​File format

​providers

​captain

​cron

​agents

​file_access

​image_config

​container_mode

​Connectors

​Cron jobs

​Tool filtering

​MCP servers

​Environment variables

​Complete example

File format

`providers`

`captain`

`cron`

`agents`

`file_access`

`image_config`

`container_mode`

Connectors

Cron jobs

Tool filtering

MCP servers

Environment variables

Complete example