Gateway & Ops / Gateway

Configuration

Genesis reads an optional JSON5 config from ~/.genesis/genesis.json. The active config path must be a regular file. Symlinked genesis.json layouts are unsupported for Genesis-owned writes; an atomic write may replace the path instead of preserving the symlink. If you keep config outside the default state directory, point GENESIS_CONFIG_PATH directly at the real file.

If the file is missing, Genesis 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.

Minimal config

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

Editing config

Interactive wizard

genesis onboard       # full onboarding flow
genesis configure     # config wizard

CLI (one-liners)

genesis config get agents.defaults.workspace
genesis config set agents.defaults.heartbeat.every "2h"
genesis config unset plugins.entries.brave.config.webSearch.apiKey

Control UI

Open http://127.0.0.1:18789 and use the Config tab. The Control UI renders a form from the live config schema, including field title / description docs metadata plus plugin and channel schemas when available, with a Raw JSON editor as an escape hatch. For drill-down UIs and other tooling, the gateway also exposes config.schema.lookup to fetch one path-scoped schema node plus immediate child summaries.

Direct edit

Edit ~/.genesis/genesis.json directly. The Gateway watches the file and applies changes automatically (see hot reload).

Strict validation

genesis config schema prints the canonical JSON Schema used by Control UI and validation. config.schema.lookup fetches a single path-scoped node plus child summaries for drill-down tooling. Field title/description docs metadata carries through nested objects, wildcard (*), array-item ([]), and anyOf/ oneOf/allOf branches. Runtime plugin and channel schemas merge in when the manifest registry is loaded.

When validation fails:

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

The Gateway keeps a trusted last-known-good copy after each successful startup. If genesis.json later fails validation (or drops gateway.mode, shrinks sharply, or has a stray log line prepended), Genesis preserves the broken file as .clobbered.*, restores the last-known-good copy, and logs the recovery reason. The next agent turn also receives a system-event warning so the main agent does not blindly rewrite the restored config. Promotion to last-known-good is skipped when a candidate contains redacted secret placeholders such as ***. When every validation issue is scoped to plugins.entries.<id>..., Genesis does not perform whole-file recovery. It keeps the current config active and surfaces the plugin-local failure so a plugin schema or host-version mismatch cannot roll back unrelated user settings.

Common tasks

Set up a channel (WhatsApp, Telegram, Discord, etc.)

Each channel has its own config section under channels.<provider>. See the dedicated channel page for setup steps:

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Feishu — channels.feishu
• Google Chat — channels.googlechat
• Microsoft Teams — channels.msteams
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Mattermost — channels.mattermost

All channels share the same DM policy pattern:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

Choose and configure models

Set the primary model and optional fallbacks:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models defines the model catalog and acts as the allowlist for /model.
• Use genesis config set agents.defaults.models '<json>' --strict-json --merge to add allowlist entries without removing existing models. Plain replacements that would remove entries are rejected unless you pass --replace.
• Model refs use provider/model format (e.g. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controls transcript/tool image downscaling (default 1200); lower values usually reduce vision-token usage on screenshot-heavy runs.
• See Models CLI for switching models in chat and Model Failover for auth rotation and fallback behavior.
• For custom/self-hosted providers, see Custom providers in the reference.

Control who can message the bot

DM access is controlled per channel via dmPolicy:

• "pairing" (default): unknown senders get a one-time pairing code to approve
• "allowlist": only senders in allowFrom (or the paired allow store)
• "open": allow all inbound DMs (requires allowFrom: ["*"])
• "disabled": ignore all DMs

For groups, use groupPolicy + groupAllowFrom or channel-specific allowlists.

See the full reference for per-channel details.

Set up group chat mention gating

Group messages default to require mention. Configure patterns per agent:

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@genesis", "genesis"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadata mentions: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
• Text patterns: safe regex patterns in mentionPatterns
• See full reference for per-channel overrides and self-chat mode.

Restrict skills per agent

Use agents.defaults.skills for a shared baseline, then override specific agents with agents.list[].skills:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Omit agents.defaults.skills for unrestricted skills by default.
• Omit agents.list[].skills to inherit the defaults.
• Set agents.list[].skills: [] for no skills.
• See Skills, Skills config, and the Configuration Reference.

Tune gateway channel health monitoring

Control how aggressively the gateway restarts channels that look stale:

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

• Set gateway.channelHealthCheckMinutes: 0 to disable health-monitor restarts globally.
• channelStaleEventThresholdMinutes should be greater than or equal to the check interval.
• Use channels.<provider>.healthMonitor.enabled or channels.<provider>.accounts.<id>.healthMonitor.enabled to disable auto-restarts for one channel or account without disabling the global monitor.
• See Health Checks for operational debugging and the full reference for all fields.

Configure sessions and resets

Sessions control conversation continuity and isolation:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main (shared) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: global defaults for thread-bound session routing (Discord supports /focus, /unfocus, /agents, /session idle, and /session max-age).
• See Session Management for scoping, identity links, and send policy.
• See full reference for all fields.

Enable sandboxing

Run agent sessions in isolated sandbox runtimes:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Build the image first: scripts/sandbox-setup.sh

See Sandboxing for the full guide and full reference for all options.

Enable relay-backed push for official iOS builds

Relay-backed push is configured in genesis.json.

Set this in gateway config:

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

CLI equivalent:

genesis config set gateway.push.apns.relay.baseUrl https://relay.example.com

What this does:

• Lets the gateway send push.test, wake nudges, and reconnect wakes through the external relay.
• Uses a registration-scoped send grant forwarded by the paired iOS app. The gateway does not need a deployment-wide relay token.
• Binds each relay-backed registration to the gateway identity that the iOS app paired with, so another gateway cannot reuse the stored registration.
• Keeps local/manual iOS builds on direct APNs. Relay-backed sends apply only to official distributed builds that registered through the relay.
• Must match the relay base URL baked into the official/TestFlight iOS build, so registration and send traffic reach the same relay deployment.

End-to-end flow:

1. Install an official/TestFlight iOS build that was compiled with the same relay base URL.
2. Configure gateway.push.apns.relay.baseUrl on the gateway.
3. Pair the iOS app to the gateway and let both node and operator sessions connect.
4. The iOS app fetches the gateway identity, registers with the relay using App Attest plus the app receipt, and then publishes the relay-backed push.apns.register payload to the paired gateway.
5. The gateway stores the relay handle and send grant, then uses them for push.test, wake nudges, and reconnect wakes.

Operational notes:

• If you switch the iOS app to a different gateway, reconnect the app so it can publish a new relay registration bound to that gateway.
• If you ship a new iOS build that points at a different relay deployment, the app refreshes its cached relay registration instead of reusing the old relay origin.

Compatibility note:

• GENESIS_APNS_RELAY_BASE_URL and GENESIS_APNS_RELAY_TIMEOUT_MS still work as temporary env overrides.
• GENESIS_APNS_RELAY_ALLOW_HTTP=true remains a loopback-only development escape hatch; do not persist HTTP relay URLs in config.

See iOS App for the end-to-end flow and Authentication and trust flow for the relay security model.

Set up heartbeat (periodic check-ins)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every: duration string (30m, 2h). Set 0m to disable.
• target: last | none | <channel-id> (for example discord, matrix, telegram, or whatsapp)
• directPolicy: allow (default) or block for DM-style heartbeat targets
• See Heartbeat for the full guide.

Configure cron jobs

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: prune completed isolated run sessions from sessions.json (default 24h; set false to disable).
• runLog: prune cron/runs/<jobId>.jsonl by size and retained lines.
• See Cron jobs for feature overview and CLI examples.

Set up webhooks (hooks)

Enable HTTP webhook endpoints on the Gateway:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

Security note:

• Treat all hook/webhook payload content as untrusted input.
• Use a dedicated hooks.token; do not reuse the shared Gateway token.
• Hook auth is header-only (Authorization: Bearer ... or x-genesis-token); query-string tokens are rejected.
• hooks.path cannot be /; keep webhook ingress on a dedicated subpath such as /hooks.
• Keep unsafe-content bypass flags disabled (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) unless doing tightly scoped debugging.
• If you enable hooks.allowRequestSessionKey, also set hooks.allowedSessionKeyPrefixes to bound caller-selected session keys.
• For hook-driven agents, prefer strong modern model tiers and strict tool policy (for example messaging-only plus sandboxing where possible).

See full reference for all mapping options and Gmail integration.

Configure multi-agent routing

Run multiple isolated agents with separate workspaces and sessions:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.genesis/workspace-home" },
      { id: "work", workspace: "~/.genesis/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

See Multi-Agent and full reference for binding rules and per-agent access profiles.

Split config into multiple files ($include)

Use $include to organize large configs:

// ~/.genesis/genesis.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

• Single file: replaces the containing object
• Array of files: deep-merged in order (later wins)
• Sibling keys: merged after includes (override included values)
• Nested includes: supported up to 10 levels deep
• Relative paths: resolved relative to the including file
• Genesis-owned writes: when a write changes top-level sections backed by single-file includes such as plugins: { $include: "./plugins.json5" }, Genesis updates each owning include file and leaves genesis.json intact — this covers genesis config set, the config RPC, and the Control UI
• Unsupported write-through: root includes, include arrays, nested includes, and includes with sibling overrides fail closed for Genesis-owned writes instead of flattening the config
• Watched: the Gateway watches include files too, so hand edits to a section file hot-reload (or restart) just like edits to genesis.json
• Error handling: clear errors for missing files, parse errors, and circular includes

genesis doctor migrates an existing monolithic config to this layout automatically on every run. It moves every splittable top-level section into ~/.genesis/config/<section>.json (for example config/models.json, config/plugins.json, config/skills.json, config/agents.json) and keeps only root metadata and restart-bound infrastructure (gateway, discovery, canvasHost) in genesis.json. The migration verifies that the resolved config is unchanged and restores the previous genesis.json if not; it still applies even if some sections currently fail schema validation, as long as splitting itself doesn't change the resolved config. Monolithic configs remain fully supported.

Config hot reload

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

Direct file edits are treated as untrusted until they validate. The watcher waits for editor temp-write/rename churn to settle, reads the final file, and rejects invalid external edits by restoring the last-known-good config. Genesis-owned config writes use the same schema gate before writing; destructive clobbers such as dropping gateway.mode or shrinking the file by more than half are rejected and saved as .rejected.* for inspection.

Plugin-local validation failures are the exception: if all issues are under plugins.entries.<id>..., reload keeps the current config and reports the plugin issue instead of restoring .last-good.

Config backups (the .bak rotation ring, .last-good, .clobbered.*, and .rejected.*) are stored in a config_backup/ folder next to genesis.json. The Control UI lists the rotation ring and .last-good under Settings -> Backups and can restore one over the live config; restoring runs through the same validation and write path, so the config being replaced is rotated into the ring first.

Gateway CRUD writes for persistent agents use this same validation and write path before the updated configuration is activated.

If you see Config auto-restored from last-known-good or config reload restored last-known-good config in logs, inspect the matching .clobbered.* file in the config_backup/ folder next to genesis.json, fix the rejected payload, then run genesis config validate. See Gateway troubleshooting for the recovery checklist.

Reload modes

{
  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.

The reload planner treats agents changes as hot. In hybrid mode, which is the default, and in hot mode, changes to agents, including agents.list writes from agents_manage, apply without a Gateway restart. restart mode still follows its explicit policy and restarts for reload-relevant changes. A turn already in progress keeps the runtime snapshot captured for that turn; subsequent turns use the refreshed agent registry.

Reload planning

When you edit a source file that is referenced through $include, Genesis plans the reload from the source-authored layout, not the flattened in-memory view. That keeps hot-reload decisions (hot-apply vs restart) predictable even when a single top-level section lives in its own included file such as plugins: { $include: "./plugins.json5" }. Reload planning fails closed if the source layout is ambiguous.

Config RPC (programmatic updates)

For tooling that writes config over the gateway API, prefer this flow:

• config.schema.lookup to inspect one subtree (shallow schema node + child summaries)
• config.get to fetch the current snapshot plus hash
• config.patch for partial updates (JSON merge patch: objects merge, null deletes, arrays replace)
• config.apply only when you intend to replace the entire config
• update.run for explicit self-update plus restart

Example partial patch:

genesis gateway call config.get --params '{}'  # capture payload.hash
genesis gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

Both config.apply and config.patch accept raw, baseHash, sessionKey, note, and restartDelayMs. baseHash is required for both methods when a config already exists.

Environment variables

Genesis reads env vars from the parent process plus:

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

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

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

Shell env import (optional)

If enabled and expected keys aren't set, Genesis runs your login shell and imports only the missing keys:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Env var equivalent: GENESIS_LOAD_SHELL_ENV=1

Env var substitution in config values

Reference env vars in any config string value with ${VAR_NAME}:

{
  gateway: { auth: { token: "${GENESIS_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Rules:

• Only uppercase names matched: [A-Z_][A-Z0-9_]*
• Missing/empty vars throw an error at load time
• Escape with $${VAR} for literal output
• Works inside $include files
• Inline substitution: "${BASE}/v1" → "https://api.example.com/v1"

Secret refs (env, file, exec)

For fields that support SecretRef objects, you can use:

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef details (including secrets.providers for env/file/exec) are in Secrets Management. Supported credential paths are listed in SecretRef Credential Surface.

See Environment for full precedence and sources.

Full reference

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

Related: Configuration Examples · Configuration Reference · Doctor

Related

• Configuration reference
• Configuration examples
• Gateway runbook