Configuration

Mayros reads an optional JSON5JSON5 supports comments and trailing commas config from ~/.mayros/mayros.json.

If the file is missing, Mayros uses safe defaults. Common reasons to add a config:

Connect channels and control who can message the bot
Set models, tools, sandboxing, or automation (cron, hooks)
Tune sessions, media, networking, or UI

See the full reference for every available field.

New to configuration? Start with mayros onboard for interactive setup, or check out the Configuration Examples guide for complete copy-paste configs.

Minimal config

json5
// ~/.mayros/mayros.json
{
  agents: { defaults: { workspace: "~/.mayros/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Editing config

bash
mayros onboard       # full setup wizard
mayros configure     # config wizard

Mayros only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start. The only root-level exception is $schema (string), so editors can attach JSON Schema metadata.

When validation fails:

The Gateway does not boot
Only diagnostic commands work (mayros doctor, mayros logs, mayros health, mayros status)
Run mayros doctor to see exact issues
Run mayros doctor --fix (or --yes) to apply repairs

Common tasks

Config hot reload

The Gateway watches ~/.mayros/mayros.json and applies changes automatically — no manual restart needed for most settings.

Reload modes

Mode	Behavior
`hybrid` (default)	Hot-applies safe changes instantly. Automatically restarts for critical ones.
`hot`	Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it.
`restart`	Restarts the Gateway on any config change, safe or not.
`off`	Disables file watching. Changes take effect on the next manual restart.

json5
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

What hot-applies vs what needs a restart

Most fields hot-apply without downtime. In hybrid mode, restart-required changes are handled automatically.

Category	Fields	Restart needed?
Channels	`channels.*`, `web` (WhatsApp) — all built-in and extension channels	No
Agent & models	`agent`, `agents`, `models`, `routing`	No
Automation	`hooks`, `cron`, `agent.heartbeat`	No
Sessions & messages	`session`, `messages`	No
Tools & media	`tools`, `browser`, `skills`, `audio`, `talk`	No
UI & misc	`ui`, `logging`, `identity`, `bindings`	No
Gateway server	`gateway.*` (port, bind, auth, tailscale, TLS, HTTP)	Yes
Infrastructure	`discovery`, `canvasHost`, `plugins`	Yes

gateway.reload and gateway.remote are exceptions — changing them does not trigger a restart.

Config RPC (programmatic updates)

Control-plane write RPCs (config.apply, config.patch, update.run) are rate-limited to 3 requests per 60 seconds per deviceId+clientIp. When limited, the RPC returns UNAVAILABLE with retryAfterMs.

Environment variables

Mayros reads env vars from the parent process plus:

.env from the current working directory (if present)
~/.mayros/.env (global fallback)

Neither file overrides existing env vars. You can also set inline env vars in config:

json5
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

See Environment for full precedence and sources.

Full reference

For the complete field-by-field reference, see Configuration Reference.