Gateway CLI - PraisonAI

The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.

from praisonaiagents import Agent

agent = Agent(name="gateway-cli-agent", instructions="Manage gateway via CLI commands.")
agent.start("Start the gateway and show its status.")

Gateway CLI provides commands for starting, monitoring, and managing the PraisonAI Gateway server and its daemon service, including channel supervision controls for resilient bot management.

# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful AI assistant."
    model: gpt-4o-mini

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    platform: telegram

# Onboarded: no flag needed — the CLI discovers ~/.praisonai/bot.yaml
praisonai gateway start

# Explicit path still wins
praisonai gateway start --config gateway.yaml

This page documents the WebSocket multi-agent Gateway daemon. The canonical CLI is praisonai-bot gateway (bot-tier package). When the praisonai wrapper is co-installed, praisonai gateway <subcommand> works as a convenience alias for every subcommand documented on this page — start, status, stop, restart, doctor, test, channels, pause / resume / reconnect, install / uninstall, mint-link, logs, send, hooks, and sessions.For the UI-Gateway (Pattern C integration), see praisonai serve ui-gateway.For detailed information about channel resilience and operator controls, see Channel Supervision.

The user runs praisonai gateway start; the CLI launches the daemon, supervises channels, and keeps the WebSocket gateway reachable.

How It Works

Quick Start

The gateway runs in the foreground. The daemon is installed by praisonai-bot gateway install (or automatically by praisonai-bot onboard).

Start Gateway

# Canonical (bot-tier, no wrapper required)
praisonai-bot gateway start

# Wrapper alias (requires pip install praisonai)
praisonai gateway start

With no --config, start auto-discovers the onboarded config and prints the file it picked before binding:

$ praisonai gateway start
Using gateway config: /Users/you/.praisonai/bot.yaml

Only one gateway can run per host:port. Stop the existing one with praisonai-bot gateway stop first, or use a different port.

Check Status

praisonai gateway status

Test Health Endpoint

curl http://127.0.0.1:8765/health

Commands

Unknown subcommands degrade gracefully. praisonai gateway <typo> prints the standard usage/error message and exits with a non-zero code, rather than dead-ending with a static list. This applies to both the canonical and wrapper entry points.

praisonai gateway … and praisonai-bot gateway … now route through one command app, so both expose the same verbs and the same start. A degraded gateway’s retry hints — praisonai gateway doctor, doctor --fix, test — name commands you can run from either binary. An unknown verb (for example praisonai gateway doctr) now prints a rendered usage error and exits non-zero instead of the old Available commands: start, status, hooks dead-end, so a new error format is expected.

Which verb do I need?

Gateway Management

Command	Description	Example
`praisonai gateway start`	Start the gateway server (foreground)	`praisonai gateway start --port 9000`
`praisonai gateway stop`	Stop a running gateway instance	`praisonai gateway stop --force`
`praisonai gateway status`	Check gateway and daemon status	`praisonai gateway status --daemon-only`
`praisonai gateway doctor`	Validate channel credentials and route/binding targets before start, run plugin health checks, and optionally auto-repair weak auth tokens (`--fix`)	`praisonai gateway doctor --config gateway.yaml --fix`
`praisonai gateway test`	One-shot readiness (probes + shell wiring + optional turn)	`praisonai gateway test --config gateway.yaml`
`praisonai gateway channels`	List configured channels (add `--probe` to check creds)	`praisonai gateway channels --probe`

praisonai-bot gateway status is safe to run on any platform. On Windows, if PID-lock inspection can’t complete, the /health probe still runs and shows the authoritative gateway status. On POSIX, a foreign-uid gateway is now correctly reported as running (rather than being treated as dead) — see PraisonAI #4197.

Daemon Service

Command	Description	Example
`praisonai gateway install`	Install as OS daemon	`praisonai gateway install --no-start`
`praisonai gateway uninstall`	Remove daemon service	`praisonai gateway uninstall`
`praisonai gateway logs`	Show daemon logs	`praisonai gateway logs -n 100`
`praisonai gateway restart`	Graceful drain + relaunch (daemon-aware)	`praisonai gateway restart --drain-timeout 30`

The installed unit stops (not restarts) on the gateway’s fatal-config exit code (78, EX_CONFIG). See Gateway Exit Codes for the full contract.

Channel Control

Command	Description	Example
`praisonai gateway pause`	Pause a channel	`praisonai gateway pause telegram`
`praisonai gateway resume`	Resume a paused channel	`praisonai gateway resume telegram`
`praisonai gateway reconnect`	Force reconnect a channel	`praisonai gateway reconnect telegram`

Inbound Hooks

Command	Description	Example
`praisonai gateway hooks add <path>`	Register an inbound webhook trigger	`praisonai gateway hooks add gmail --agent assistant`
`praisonai gateway hooks list`	List registered hooks	`praisonai gateway hooks list`
`praisonai gateway hooks remove <path>`	Remove an inbound hook	`praisonai gateway hooks remove gmail`

See Gateway Inbound Hooks for full details.

Testing & Debugging

Command	Description	Example
`praisonai gateway test`	Full readiness check (see Gateway Readiness)	`praisonai gateway test --config gateway.yaml --channel slack --turn "Say OK"`
`praisonai gateway send`	Send test message	`praisonai gateway send --channel telegram --channel-id 12345 -m "test"`
`praisonai gateway diagnostics export`	Write a pre-sanitised support bundle (see Diagnostics Export)	`praisonai gateway diagnostics export --config gateway.yaml`

Diagnostics

praisonai gateway diagnostics export writes a portable, pre-sanitised .zip you can attach to a bug report. Full details in Diagnostics Export.

Flag	Type	Default	Description
`--config`, `-c`	`str`	`"gateway.yaml"`	Path to `gateway.yaml`.
`--output-dir`	`str \| None`	`~/.praisonai/diagnostics`	Directory to write the bundle.
`--log-lines`	`int`	`200`	Number of recent (redacted) log lines to include.
`--json`	`bool`	`False`	Emit JSON (`{path, manifest}`) instead of the human summary.

Command Reference

For the channel-control verbs (pause / resume / reconnect), when --url is omitted the target is resolved from --host / --port (defaulting to the GATEWAY_PORT environment variable, then 127.0.0.1:8765). Previously the URL was always probed at 127.0.0.1:8765 — operators running the gateway on a non-default endpoint had to hand-type the WebSocket URL for every channel control call.

praisonai gateway start [OPTIONS]

Options:
  --host TEXT                     Host to bind to [default: 127.0.0.1]
  --port INTEGER                  Port to listen on [default: 8765 or $GATEWAY_PORT]
  --agents TEXT                   Path to agent configuration file
  --config TEXT                   Path to gateway.yaml for multi-bot mode.
                                  When omitted, auto-discovers the onboarded
                                  config (./bot.yaml → ~/.praisonai/bot.yaml →
                                  ./gateway.yaml alias) and prints
                                  "Using gateway config: <path>". Exits 78 with
                                  an onboard hint if none is found.
  --reliability [production|default|off]
                                  Reliability preset — composes drain + admission.
                                  production (15s drain + CPU-scaled admission),
                                  default (5s drain, no admission), off (immediate teardown).
                                  Overrides `reliability:` from YAML but is overridden
                                  by explicit --drain-timeout / --max-concurrent-runs.
  --preflight / --no-preflight    Validate channel credentials before
                                  starting (fail fast on bad tokens)
                                  [default: --preflight]
  --strict-tools / --no-strict-tools
                                  Fail fast if any tool named in the config
                                  cannot be resolved. Use --no-strict-tools to
                                  skip unresolved tools and start anyway (#3553)
                                  [default: --strict-tools]
  --verify-turn / --no-verify-turn
                                  Run one real agent turn before serving so a
                                  missing/invalid model credential fails at
                                  startup, not on the first user message.
                                  Default: on (reads
                                  gateway.preflight.verify_turn, defaults to
                                  true). Use --no-verify-turn for constrained/
                                  offline environments (#4042).
  --identity-store TEXT           Path to the cross-platform identity link-map
                                  JSON (default ~/.praisonai/identity.json).
                                  Enables one continuous session + memory per
                                  paired/linked user across channels (#3020).
                                  Overrides the `identity:` block in gateway.yaml.
  --scale-to-zero                 Quiesce the gateway when idle for --idle-minutes
                                  (scale-to-zero; #3021). Overrides
                                  lifecycle.scale_to_zero.enabled in gateway.yaml.
  --idle-minutes FLOAT            Minutes of no inbound / in-flight work before
                                  quiescing (#3021). Overrides
                                  lifecycle.scale_to_zero.idle_minutes.
  --drain-marker TEXT             Path to watch for an epoch-aware external drain
                                  marker file (#3021). Overrides
                                  lifecycle.drain.marker_path.

Examples:
  praisonai gateway start                        # onboarded: discovers ~/.praisonai/bot.yaml
  praisonai gateway start --config gateway.yaml  # explicit path still wins
  praisonai gateway start --agents agents.yaml --port 9000
  praisonai gateway start --config gateway.yaml --no-preflight
  praisonai gateway start --config gateway.yaml --no-strict-tools
  praisonai gateway start --config gateway.yaml --no-verify-turn
  praisonai gateway start --config gateway.yaml --reliability production
  GATEWAY_PORT=9000 praisonai gateway start

  # Enable cross-platform continuity without touching gateway.yaml
  praisonai gateway start --config gateway.yaml \
    --identity-store ~/.praisonai/identity.json

  # Enable scale-to-zero + external drain marker without touching gateway.yaml
  praisonai gateway start --config gateway.yaml \
    --scale-to-zero --idle-minutes 10 \
    --drain-marker /data/gateway.drain

The lifecycle flags synthesize a lifecycle: block, so CLI overrides win over YAML. --scale-to-zero arms and quiesces even without a wake_url — the gateway keeps its listening socket open and self-wakes on the next inbound message. See Scale-to-Zero, Drain Trigger, and Crash-Loop Guard.

--reliability overrides the reliability: / gateway.reliability: key in YAML. See Gateway Reliability Presets for profile details and precedence rules.

--identity-store gives every paired/linked user one continuous session across channels and overrides the identity: block in gateway.yaml. See Cross-Platform Sessions → In the gateway for the full precedence ladder.

Corporate proxies / SSL-inspecting networks. A preflight failure caused only by SSLCertVerificationError / certificate_verify_failed does not abort the start — the token is usually valid and the runtime adapter’s SSL stack is more permissive. The gateway prints a one-line warning naming the three CA-bundle env vars and continues.If any channel also fails for a non-SSL reason (bad token, unreachable host, timeout), preflight still hard-aborts — fix that channel or pass --no-preflight. See Corporate CA bundle (SSL-inspecting networks).

--verify-turn is governed by its own toggle, independent of --preflight. --no-preflight --verify-turn skips the channel-credential probe but still runs one real model round-trip. Both checks run by default and the turn check never replaces the channel probe. On failure it prints the error and exits 1. Prompt and timeout are YAML-only (gateway.preflight.verify_turn_prompt / verify_turn_timeout) — there is no --verify-turn-prompt flag. See Gateway Readiness → Turn pre-flight.

praisonai gateway stop [OPTIONS]

Options:
  --host TEXT         Gateway host [default: 127.0.0.1]
  --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
  --force             Force stop (kill process)

Examples:
  praisonai gateway stop
  praisonai gateway stop --port 9000
  praisonai gateway stop --force

praisonai gateway stop performs a graceful drain — it waits up to 10 seconds for in-flight agent turns and queued messages before closing. Use --force to skip the drain and terminate immediately.

praisonai gateway status [OPTIONS]

Options:
  --host TEXT         Gateway host [default: 127.0.0.1]
  --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
  --daemon-only       Show only daemon status

Examples:
  praisonai gateway status
  praisonai gateway status --port 9000
  praisonai gateway status --daemon-only

praisonai gateway doctor [OPTIONS]

Options:
  -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml — resolves to
                      the onboarded ~/.praisonai/bot.yaml when present]
  --json              Output JSON
  --channel TEXT      Channel a --turn probe uses (default: first configured)
  --turn TEXT         Run one offline inbound agent turn via
                      BotSessionManager.chat (requires LLM API key)
  --fix               Repair safe findings (mint a strong gateway auth token
                      when weak/missing), then re-validate
  --dry-run           With --fix, preview repairs without writing anything

Examples:
  praisonai gateway doctor
  praisonai gateway doctor --fix
  praisonai gateway doctor --fix --dry-run
  praisonai gateway doctor --config my-gateway.yaml --json
  praisonai gateway doctor --config gateway.yaml --channel slack --turn "Say OK"
  praisonai gateway doctor --config gateway.yaml --json --channel slack --turn "Say OK"

--turn runs an offline agent turn via BotSessionManager.chat. It does not exercise Slack Bolt/socket handlers or @mention routing — a passing turn test does not guarantee live @mention delivery.

praisonai gateway test [OPTIONS]

Options:
  -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml — resolves to
                      the onboarded ~/.praisonai/bot.yaml when present]
  --json              Output JSON (single top-level document)
  --channel TEXT      Target channel for --turn (must exist in config)
  --turn TEXT         Offline inbound agent turn via BotSessionManager.chat
                      (requires LLM API key)
  --check-running     Probe REST /info on the running gateway to confirm
                      reachability

Examples:
  praisonai gateway test
  praisonai gateway test --config gateway.yaml
  praisonai gateway test --config gateway.yaml --channel slack \
    --turn "run uname -a with execute_command"
  praisonai gateway test --config gateway.yaml --check-running
  praisonai gateway test --config gateway.yaml --json

test combines credential probes with offline shell wiring validation, then layers optional checks (--turn, --check-running). See Gateway Readiness for the full three-tier checklist.

--turn runs an offline agent turn via BotSessionManager.chat. It does not exercise Slack Bolt/socket handlers or @mention routing.

praisonai gateway mint-link [OPTIONS]

Options:
  --ttl INTEGER   Link time-to-live in seconds [default: 600]

Examples:
  praisonai gateway mint-link
  praisonai gateway mint-link --ttl 3600

mint-link prints a fresh pairing/magic link that binds a cross-platform identity to the gateway, and also writes it to ~/.praisonai/last-link.txt (mode 600). The link resolves against GATEWAY_HOST / GATEWAY_PORT (defaulting to 127.0.0.1:8765). It exits 1 when magic-link support is unavailable.

praisonai gateway sessions [OPTIONS]

Examples:
  praisonai gateway sessions          # inspect per-channel session store entries

sessions inspects — and can prune — the per-channel session store so an operator can see live conversations without opening the store by hand.

praisonai gateway logs [OPTIONS]

Options:
  -n INTEGER   Number of trailing lines to show

Examples:
  praisonai gateway logs
  praisonai gateway logs -n 100

logs tails the gateway’s stdout/stderr under the daemon runner (~/.praisonai/logs/bot-stderr.log on macOS; journalctl --user -u praisonai-bot on Linux).

praisonai gateway send [OPTIONS]

Options:
  --channel TEXT       Channel to push through (e.g. telegram)
  --channel-id TEXT    Destination id on that channel
  -m, --message TEXT   Message body

Examples:
  praisonai gateway send --channel telegram --channel-id 12345 -m "test"

send pushes a one-off message through the outbound messenger so you can smoke-test delivery to a real channel without waiting for an inbound trigger.

praisonai gateway channels [OPTIONS]

Options:
  -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml — resolves to
                      the onboarded ~/.praisonai/bot.yaml when present]
  --json              Output JSON format
  --probe             Probe each channel's credentials

Examples:
  praisonai gateway channels
  praisonai gateway channels --config my-gateway.yaml --json
  praisonai gateway channels --probe

praisonai gateway pause <channel-name> [OPTIONS]

Options:
  --host TEXT   Gateway host [default: 127.0.0.1]
  --port INTEGER Gateway port [default: 8765 or $GATEWAY_PORT]
  --url TEXT    Gateway WebSocket URL — resolved from --host/--port when omitted

Examples:
  praisonai gateway pause telegram
  praisonai gateway pause telegram --port 9000        # non-default port
  GATEWAY_PORT=9000 praisonai gateway pause telegram  # via env
  praisonai gateway pause discord --url ws://localhost:8000  # explicit URL still wins

praisonai gateway resume <channel-name> [OPTIONS]

Options:
  --host TEXT   Gateway host [default: 127.0.0.1]
  --port INTEGER Gateway port [default: 8765 or $GATEWAY_PORT]
  --url TEXT    Gateway WebSocket URL — resolved from --host/--port when omitted

Examples:
  praisonai gateway resume telegram
  praisonai gateway resume telegram --port 9000        # non-default port
  GATEWAY_PORT=9000 praisonai gateway resume telegram  # via env
  praisonai gateway resume discord --url ws://localhost:8000  # explicit URL still wins

praisonai gateway reconnect <channel-name> [OPTIONS]

Options:
  --host TEXT   Gateway host [default: 127.0.0.1]
  --port INTEGER Gateway port [default: 8765 or $GATEWAY_PORT]
  --url TEXT    Gateway WebSocket URL — resolved from --host/--port when omitted

Examples:
  praisonai gateway reconnect telegram
  praisonai gateway reconnect telegram --port 9000        # non-default port
  GATEWAY_PORT=9000 praisonai gateway reconnect telegram  # via env
  praisonai gateway reconnect discord --url ws://localhost:8000  # explicit URL still wins

Config discovery

You no longer need --config if you have onboarded — praisonai gateway start discovers the config praisonai onboard wrote. Every gateway command (start, doctor, test, status, send, channels) uses the same canonical resolution order, so onboard, start, and doctor cannot drift apart.

praisonai onboard          # writes ~/.praisonai/bot.yaml
praisonai gateway start    # discovers it — no flag needed

Precedence	Source	Notes
1	`--config <path>` / `--agents <path>`	Explicit path always wins
2	`./bot.yaml` (cwd)	Local project override
3	`$PRAISONAI_BOT_CONFIG` / `~/.praisonai/bot.yaml`	Env var — `PRAISONAI_HOME`-aware; where `praisonai onboard` writes
4	`./gateway.yaml` (cwd)	Backward-compatible alias — legacy name
—	none	Print onboard hint, exit `78`

bot.yaml is the canonical name. gateway.yaml continues to load without warning as a backward-compatible alias — it is not the new preferred name. When the optional praisonai-code package is installed, its resolve_bot_config_path resolver is used; a lean install without it falls through to an equivalent inline resolver that agrees on every path.

`start` with no config

praisonai gateway start (no --config, no --agents) discovers the onboarded config, prints Using gateway config: <path>, then binds with channels instead of the earlier silent WebSocket-only no-op. If nothing is found it prints a hint and exits 78:

$ praisonai gateway start
No gateway config found. Run 'praisonai onboard' to create one, or pass
--config <path> (or --agents <path> for single-agent mode).
$ echo $?
78

Passing --agents <path> selects single-agent mode and skips channel-config discovery.

`doctor` / `test` / `status` / `send` / `channels`

These commands default --config to a gateway.yaml sentinel. When you leave it at the default, they run the same discovery order as start — so praisonai gateway doctor after praisonai onboard inspects the onboarded ~/.praisonai/bot.yaml, not a file onboarding never wrote. An explicit --config always wins.

The Path to gateway.yaml [default: gateway.yaml] help text on these commands resolves to the onboarded ~/.praisonai/bot.yaml when present — the literal gateway.yaml file is only used as the final alias fallback.

Version validation

praisonai gateway start also validates the config’s config_version before binding, applying the same forward-migration doctor --fix uses. A config from a newer build refuses to start (exit 78) rather than being silently downgraded. See Gateway Config Migration › Config version stamp.

What the user sees

The whole reason this discovery exists: before, an onboarded operator who ran praisonai gateway start with no flag started silently channel-less, so their Telegram user got no reply.

Two behaviours change observably for existing operators — the CLI stopped silently doing the wrong thing.

gateway start with no flag now discovers ~/.praisonai/bot.yaml. A deploy that relied on the old silent channel-less shape (WebSocket daemon only) now starts with the onboarded channels attached. To keep the old behaviour, point --config at a channel-less YAML explicitly, or remove ~/.praisonai/bot.yaml.
gateway start refuses to run a config from a newer build. A host that pinned an older praisonaiagents while keeping a newer config now sees exit 78 at start instead of a silent downgrade. Upgrade the wrapper, or roll the config back to the version the wrapper supports.

For a focused, standalone walkthrough of this resolution, see Gateway Config Discovery. Start-time version validation is documented in Config Migration → At start time.

Pre-flight credential check

praisonai gateway doctor validates every channel’s token before the gateway starts, so a bad or expired credential fails fast with a precise per-channel reason instead of disappearing into the supervisor’s silent reconnect loop.

Examples

Quick health check:

$ praisonai gateway doctor
telegram     ✓  @my_support_bot
slack        ✗  SSL certificate verify failed (network/proxy?). Token may still be valid. Try SSL_CERT_FILE=/path/to/corp-ca.pem or gateway start --no-preflight
discord      ✓  @MySupport

A non-SSL failure keeps the bare error string:

$ praisonai gateway doctor
telegram     ✓  @my_support_bot
slack        ✗  invalid_auth (token expired)
discord      ✓  @MySupport

CI-friendly JSON — a single document with a probes block (and a secrets block when any channel uses a secret reference):

$ praisonai gateway doctor --json
{
  "probes": {
    "telegram": {"ok": true,  "platform": "telegram", "bot_username": "my_support_bot"},
    "slack":    {"ok": false, "platform": "slack",    "error": "invalid_auth"},
    "discord":  {"ok": true,  "platform": "discord",  "bot_username": "MySupport"}
  },
  "secrets": {
    "telegram": {"token": "available"},
    "slack":    {"token": "available", "app_token": "configured-but-unavailable"},
    "discord":  {"token": "configured"}
  }
}

The whole output is now one JSON document ({probes, secrets}), parseable with a single json.loads. Operator scripts that read the earlier two-document output (a probe block plus a separate availability block) must switch to reading payload["probes"]. A weak gateway auth_token adds a third top-level key, gateway_auth_token — see Weak-secret check.

Same verdict via the listing command:

$ praisonai gateway channels --probe

Credential availability (without revealing values)

praisonai gateway doctor also prints a per-channel credential availability table so operators can validate secret wiring — including the secret-reference form on token, app_token, and verify_token — without ever printing a value.

$ praisonai gateway doctor
Credential availability (values never shown):
telegram     token         ✓  available
slack        token         ✓  available
slack        app_token     ✗  configured-but-unavailable
whatsapp     verify_token  ✗  missing

State	Meaning
`available`	Resolved successfully (env set, file present and non-empty)
`configured-but-unavailable`	Configured but cannot resolve (empty file, unreadable, empty env var)
`configured`	An `exec` reference — configured, but not executed at probe time
`missing`	Not set (env var unset, file not found)

An exec-sourced reference reports configured without running its command: the command has side effects (a one-shot / rate-limited / rotating secret-manager call) and the network probe resolves the same reference moments later, so executing it here would run it twice. These states now map cleanly to runtime isolation at boot — a configured-but-unavailable or missing channel credential isolates just that channel as degraded rather than aborting the gateway. See Degraded Channel Isolation. After boot, GET /health emits the same degraded / reason: "credential unavailable" verdict for a channel whose token is rejected at runtime (401/403, revoked/rotated/expired) — no new flags. See Runtime credential rejection. The --json output is a single document with probes and secrets keys:

{
  "probes":  { "telegram": {"ok": true }, "slack": {"ok": false} },
  "secrets": { "telegram": {"token": "available"},
               "slack":    {"token": "available", "app_token": "configured-but-unavailable"} }
}

Breaking change to the --json layout. Previously doctor printed the availability and probe blocks as two separate top-level documents (invalid JSON). It now emits one document with probes and secrets keys, so json.loads can parse the whole output. The secrets key is present only when at least one channel configures a credential field.

Weak-secret check

gateway doctor also flags the gateway’s own auth_token when it matches a well-known placeholder — fails on an external bind, warns on loopback. On an external bind with a weak token, doctor prints the full refusal message and exits 1:

$ praisonai gateway doctor --config gateway.yaml
Refusing to start: gateway.auth_token is a known-weak/placeholder value.
A publicly-known secret provides no real authentication.
Fix:  praisonai onboard         (30 seconds, 3 prompts)
Or:   export GATEWAY_AUTH_TOKEN="$(openssl rand -hex 16)"  (run in a shell so the command is expanded, not pasted literally)

On a loopback bind, doctor prints a warning and still exits 0:

$ praisonai gateway doctor --config gateway.yaml
⚠  gateway.auth_token is a known-weak/placeholder value (loopback bind 127.0.0.1). Rotate before exposing externally.

A strong token prints nothing extra — silence is a pass, consistent with the credential-availability table. The --json output gains a top-level gateway_auth_token key (present only when the verdict is weak), alongside probes and secrets. When --fix is passed, an optional fix key carries the repair report:

{
  "probes":  { "telegram": {"ok": true} },
  "secrets": { "telegram": {"token": "available"} },
  "gateway_auth_token": "weak",
  "fix": "gateway_auth_token: weak → generated a strong token… done\nre-validated: gateway_auth_token now strong"
}

Verdict	Bind	Exit code
Weak / missing `auth_token`	External	`1`
Weak `auth_token`	Loopback	`0` (warning only)
Strong `auth_token`	Any	`0`

Weak Secret Guard

Full denylist, bind-aware behaviour matrix, and how to fix a weak change-me-style token

Auto-repair with `--fix`

Prefer Python for CI, tests, or per-tenant provisioning? The same repair lifecycle is exposed as praisonai_bot.repair_gateway_config — see Gateway Admin API.

--fix repairs safe findings, then re-validates that each finding cleared. Repair a weak token, then confirm it cleared:

$ praisonai gateway doctor --config gateway.yaml --fix
gateway_auth_token: weak → generated a strong token… done
re-validated: gateway_auth_token now strong

Preview the repair without writing anything:

$ praisonai gateway doctor --config gateway.yaml --fix --dry-run
gateway_auth_token: weak → would mint a strong token (--dry-run)

Finding	`--fix` action	Persistence
`gateway.auth_token` weak/missing	Mint `secrets.token_hex(16)`, export to env, persist to `~/.praisonai/.env`	Survives daemon restart
`gateway.auth_token` explicit weak in YAML	Also rewrites `gateway.yaml` in place (preserves `${ENV}` references)	Config file updated
Any other finding	Not repaired yet (no dead-end: still surfaced with its own `retry_hint`)	—

--dry-run still exits 1 when a repairable finding is present, so CI catches un-fixed states before anything is written.

--fix writes to ~/.praisonai/.env and may rewrite an explicit weak auth_token in gateway.yaml in place. Run --fix --dry-run first in production to preview the change. ${ENV} references in YAML are left untouched — they resolve from the env store the env-var repair already fixed.

Pre-flight gate on start

praisonai gateway start runs the same probe automatically before launch when invoked with --config gateway.yaml:

$ praisonai gateway start --config gateway.yaml
slack        ✗  invalid_auth (token expired)

Pre-flight check failed — aborting start. Fix the channel credentials
above or pass --no-preflight to skip.

To bypass during local dev (e.g. flaky probe network):

praisonai gateway start --config gateway.yaml --no-preflight

Route/binding target check

praisonai gateway doctor also validates that every routes, routing, and bindings.agent target names an agent declared in the sibling agents: map. A typo — including in the default slot — fails with a “did you mean X?” hint instead of silently misrouting traffic.

$ praisonai gateway doctor --config gateway.yaml
ERROR: Invalid gateway/bot configuration:
channel 'telegram' route 'dm' -> unknown agent 'personl'; did you mean 'personal'? valid agents: personal, support

This runs only for multi-agent configs (an agents: map is present). Single-bot configs (top-level platform + token) are unaffected. See Fail-Fast Validation for the full behaviour.

Corporate CA bundle (SSL-inspecting networks)

On networks that intercept TLS with a corporate CA (proxy / MITM), the probe’s HTTP client can reject the certificate chain even though the token is valid and the runtime adapter connects fine. Preflight classifies these SSL cert-verify failures separately and soft-fails when they are the only failures.

$ praisonai gateway start --config gateway.yaml
slack        ✗  SSL certificate verify failed (network/proxy?). Token may still be valid. Try SSL_CERT_FILE=/path/to/corp-ca.pem or gateway start --no-preflight

Pre-flight found SSL certificate-verify failures only (likely a proxy/MITM
network). Tokens may still be valid — continuing start. Set SSL_CERT_FILE /
REQUESTS_CA_BUNDLE / PRAISONAI_SSL_CA_BUNDLE to your corporate CA, or pass
--no-preflight to skip this check.

The probe decides its action from the mix of failures:

Probe outcome (across all channels)	Preflight action
All channels `ok`	Start proceeds silently.
≥1 channel fails with a non-SSL error (token, network, timeout)	Hard-abort, exit `1`.
All failures are SSL cert-verify only	Soft-fail — print the SSL warning, continue to start, exit `0`.
Mixed: ≥1 SSL cert-verify and ≥1 token/network failure	Hard-abort (the non-SSL failure wins), exit `1`.

Only certificate-verify failures soft-fail. Other TLS handshake failures — WRONG_VERSION_NUMBER, NO_SHARED_CIPHER, HANDSHAKE_FAILURE — still hard-abort, because they usually indicate a real bug that also breaks the channel at runtime.

Point the probe at your corporate CA with one of three env vars, highest precedence first:

Variable	Precedence	Behaviour
`PRAISONAI_SSL_CA_BUNDLE`	Highest — explicit PraisonAI override	Overrides pre-existing `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` for the probe.
`REQUESTS_CA_BUNDLE`	Middle	Used only if `PRAISONAI_SSL_CA_BUNDLE` is unset. Left alone when the winner came from elsewhere.
`SSL_CERT_FILE`	Lowest — Python default	Read by Python’s default `ssl` context (used by `aiohttp`). Used only if the two above are unset.

export PRAISONAI_SSL_CA_BUNDLE=/path/to/corp-ca.pem
praisonai gateway start --config gateway.yaml

A configured-but-missing path warns and leaves the SSL env vars untouched:

Warning: CA bundle path '<path>' does not exist — SSL_CERT_FILE / REQUESTS_CA_BUNDLE not updated for probe.

The runtime adapter reads the same three env vars, so setting one fixes both the preflight probe and long-lived channel connections.

Token resolution

The probe loads ~/.praisonai/.env first, so ${VAR} placeholders set by praisonai onboard resolve exactly like they do at runtime — doctor, channels --probe, and start --preflight all share the same token-resolution path.

Per-channel timeout

Each probe is bounded by a 15-second deadline; a stuck adapter is reported as "probe timed out after 15s" and does not hang the aggregate.

Exit codes

Outcome	Exit code
All channels probe OK	`0`
Any channel fails	`1`
Weak / missing gateway `auth_token` on an external bind	`1`
Weak gateway `auth_token` on a loopback bind (warning only)	`0`
`gateway doctor` with no channels configured	`0`

When to use which

Programmatic check (Python)

import asyncio
from praisonai.bots import Bot, BotOS

botos = BotOS(
    bots=[
        Bot("telegram", token="..."),
        Bot("slack",    token="..."),
    ],
    enable_supervision=False,
)

results = asyncio.run(botos.probe_all(timeout=15.0))
for platform, r in results.items():
    print(platform, "ok" if r.ok else r.error)

Pre-flight tool check

praisonai gateway start validates every tool named in your config before the gateway binds, so a typo or an uninstalled optional package fails fast with a per-name reason instead of silently starting a quietly under-powered bot.

Default changed 2026-07-31. Before PR #3555 an unresolved tool was silently skipped with only a log warning. The default is now --strict-tools, which aborts start with exit 78 and a per-name fix hint. Configs with typo’d or unavailable tools that previously started will now fail — pass --no-strict-tools or set strict_tools: false in gateway.yaml to restore the old warn-and-continue behaviour.

This gate runs one layer above the core resolver’s PRAISONAI_STRICT_TOOLS / ToolResolutionError mechanism — it fires at start-time, before GatewayHandler.start() builds any agent. See Tool Resolution for the complementary core-resolver behaviour.

Strict mode (default) — fail fast

$ praisonai gateway start --config gateway.yaml
✗ Tool pre-flight failed:
    - 'duckduckgo_serch' not found. Did you mean 'duckduckgo'?
  Fix the names in your config, or start with --no-strict-tools to run without them.
$ echo $?
78

Non-strict — warn and continue

Two equivalent ways:

CLI flag
YAML key

praisonai gateway start --config gateway.yaml --no-strict-tools

# gateway.yaml
strict_tools: false
agents:
  assistant:
    instructions: "..."
    tools: [duckduckgo_serch]        # unresolved but tolerated

Either produces:

⚠ Tool pre-flight (non-strict) — starting without:
    - 'duckduckgo_serch' not found. Did you mean 'duckduckgo'?

“Did you mean?” mechanics

Suggestions use stdlib difflib.get_close_matches (cutoff 0.7, one suggestion per unknown). A tool that is registered but currently unloadable (e.g. an optional package not installed) is excluded from its own candidates, so it yields an install hint rather than suggesting the same name back:

'firecrawl' not found in any source. Check the spelling, install the package
that provides it, or set PRAISONAI_ALLOW_LOCAL_TOOLS=true for a local tools.py.

A project tools.py that exists but is gated by the local-tools env var is flagged explicitly:

'my_local' not found. A local tools.py exists but local tools are disabled;
set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable it.

An unknown toolset name is reported the same way:

    - toolset:research not found (unknown toolset)

Precedence

Setting	Result
YAML `strict_tools: false`	Gate disabled (regardless of CLI flag)
CLI `--no-strict-tools`	Gate disabled for this invocation
CLI `--strict-tools` (default) with no YAML override	Gate strict → fail fast on any unresolved tool
No unresolved tools	Pre-flight is silent, start proceeds

YAML strict_tools: false opts a bot out permanently; --no-strict-tools is per-invocation. A strict CLI default does not override a YAML strict_tools: false.

Env loading

The gate loads ~/.praisonai/.env before resolving, so PRAISONAI_ALLOW_LOCAL_TOOLS=true stored there by praisonai onboard is honoured and a gated local tools.py is not falsely reported as unresolved. The load is idempotent and existing process env wins — GatewayHandler.start() re-loads the same file moments later.

Exit code

Strict failure exits with 78 (EX_CONFIG), which the OS units generated by praisonai gateway install treat as do-not-restart — an unresolvable tool in the config would loop the daemon otherwise. See Gateway Exit Codes.

Environment Variables

Variable	Description	Default
`GATEWAY_PORT`	Port for start/stop/status when —port is not passed	`8765`

The GATEWAY_PORT environment variable is used by start, stop, and status commands when the --port option is not explicitly provided. Invalid values silently fall back to 8765.

Supervisor exit codes

praisonai gateway start returns a supervisor-friendly exit code so a service manager (launchd / systemd / a scheduled task) knows whether to restart the gateway or stop and wait for an operator.

Code	Meaning	When you see it
`0`	Clean shutdown / success	Ctrl+C, `SIGTERM` drain, `stop`, a healthy `status`
`75`	Transient failure — supervisor should restart	Network blip, port contention, transient IO
`78`	Fatal configuration error — supervisor should stop	Bad `gateway.yaml`, no platforms, duplicate token, unresolved strict tool

The installed OS unit maps 78 (EX_CONFIG) to do-not-restart so a broken config cannot crash-loop the daemon, and treats 75 (EX_TEMPFAIL) as restartable. See Gateway Exit Codes for the full contract and per-platform wiring.

The doctor verb uses a simpler 0 / 1 scheme (pass / fix-me) documented under Pre-flight credential check → Exit codes — that is separate from the start supervisor protocol above.

Single-Instance Enforcement

PraisonAI enforces a single gateway instance per host:port combination using PID locks. Lock File Location: ~/.praisonai/gateway-<safe_host>-<port>.pid The safe_host replaces : and . with _ (so 127.0.0.1 becomes 127_0_0_1). Each host:port combination gets its own lock file, allowing multiple gateways on different ports.

PID-Lock Status Reference

praisonai gateway status prints one PID-lock line before the /health probe. Look up any line you see:

Line printed	When
`Gateway PID lock: Process <pid> running (<host>:<port>)`	Lock file exists, PID responds to `os.kill(pid, 0)` and the recorded start-time fingerprint matches
`Gateway PID lock: Stale lock (process <pid> not running)`	Lock file exists, but the PID no longer responds or its start time no longer matches the fingerprint (including Windows `SystemError`/`ValueError` cases)
`Gateway PID lock: No lock file found`	No lock file at `~/.praisonai/gateway-<safe_host>-<port>.pid`
`PID lock status: Utilities not available`	`port_utils` import failed (`ImportError`)
`PID lock status: Unavailable (<error>)`	Any other unexpected exception during PID-lock inspection; the `/health` probe still runs

The port line (Port <host>:<port>: In use / Available) follows the same section unless PID-lock inspection fails, in which case the single PID lock status: Unavailable (<error>) line replaces both.

Since PR #4197, the lock records a PID + start-time fingerprint (a 5th line). “Running” means the PID is alive and its start time matches, so a recycled PID is not mistaken for the original gateway. A missing fingerprint (older 4-line lock or psutil unavailable) degrades gracefully to the previous PID-only check. On POSIX, a live gateway owned by another user (PermissionError from os.kill) is also treated as running, so its lock is preserved.

Restart the Gateway

Use praisonai gateway restart — it drains in-flight turns, then relaunches (via the installed service manager when present, otherwise directly).

# Simple restart with default 10s drain
praisonai gateway restart

# Restart pointing at a config (needed only for the direct-relaunch fallback)
praisonai gateway restart --config gateway.yaml

# Longer drain window for slow agent turns
praisonai gateway restart --drain-timeout 30

# Restart a gateway running on a non-default endpoint
praisonai gateway restart --host 127.0.0.1 --port 9000
# equivalently:  GATEWAY_PORT=9000 praisonai gateway restart

gateway restart is daemon-aware: if the gateway is installed as an OS service (praisonai gateway install), the platform service manager restarts it (launchctl kickstart -k, systemctl --user restart praisonai-bot, or schtasks /End && /Run) so the installed unit’s launch flags are preserved. Otherwise the CLI drains the running PID and relaunches directly in the foreground.

The direct (non-service) fallback now replays the CLI-only flags the original process was started with (--openai-api, --mcp, --reliability, --max-concurrent-runs, --queue-depth, --overflow-policy, --identity-store, --scale-to-zero, --idle-minutes, --drain-marker, --agents, --config, --drain-timeout) from a persisted start-flags artefact — see Persisted start-flags artefact. Flags passed explicitly to restart still win; anything else replays the value the running process was launched with.

Options

Flag	Type	Default	Description
`--host`	`str`	`127.0.0.1`	Gateway host (used to locate the running instance)
`--port`	`int`	`GATEWAY_PORT` env, else `8765`	Gateway port
`--config`	`str`	none	Path to `gateway.yaml` for direct-relaunch fallback
`--agents`	`str`	none	Path to agent configuration file for direct-relaunch fallback
`--drain-timeout`	`Optional[float]`	persisted start value, else `10.0`	Seconds to wait for in-flight agent turns before relaunch. Omit to replay the persisted start value; explicit value wins over the persisted one and applies to both the OLD-process drain and the relaunch.

Persisted start-flags artefact

praisonai gateway start persists the CLI-only runtime flags it was launched with to ~/.praisonai/gateway.start.<host>.<port>.json so a later praisonai gateway restart (direct, non-service path) reproduces the exact posture instead of silently reverting to defaults. Path: ~/.praisonai/gateway.start.<safe_host>.<port>.json (or $PRAISONAI_HOME/gateway.start.<safe_host>.<port>.json when set). safe_host replaces : with _, so IPv6 hosts work. The artefact is keyed by host:port — multiple gateways on one machine each keep their own posture. Persisted keys (only non-None values are stored — None means “fall back to YAML”):

Key	Corresponds to
`agent_file`	`--agents`
`config_file`	`--config`
`drain_timeout`	`--drain-timeout`
`max_concurrent_runs`	`--max-concurrent-runs`
`queue_depth`	`--queue-depth`
`overflow_policy`	`--overflow-policy`
`reliability`	`--reliability`
`openai_api`	`--openai-api`
`mcp`	`--mcp`
`identity_store`	`--identity-store`
`scale_to_zero`	`--scale-to-zero`
`idle_minutes`	`--idle-minutes`
`drain_marker`	`--drain-marker`

Write timing: the artefact is written only after startup validation passes (config parse, agent-file parse, admission wiring), immediately before the gateway binds. A start attempt that fails validation on the same host:port never clobbers the running gateway’s saved posture — otherwise the next restart would faithfully replay a rejected attempt.

On restart, gateway restart prints Replaying persisted start flags: <sorted keys> before relaunching, so operators see exactly which flags were replayed.

Precedence on restart: An omitted --drain-timeout on restart no longer forces a fixed 10s window; it replays the persisted value (and only falls back to 10.0 when nothing is persisted). An explicit --drain-timeout still wins over the persisted value for both the OLD-process drain and the relaunch, so a long configured drain is not silently cut off. Fixes #3349.

On Windows, gateway restart aborts if schtasks /End fails — this prevents a duplicate / colliding gateway relaunch that the raw /End && /Run chain would silently produce.

Advanced: OS-native restart

If you need to bypass the CLI (e.g. from a systemd ExecStartPre), the same platform commands the daemon dispatcher uses are:

macOS
Linux
Windows

launchctl kickstart -k gui/$(id -u)/ai.praison.bot

systemctl --user restart praisonai-bot

schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway

Bypassing gateway restart skips the graceful drain — in-flight agent turns will be interrupted mid-response. Prefer the CLI verb.

Status Output Examples

Healthy Gateway

$ praisonai gateway status
Gateway PID lock: Process 12345 running (127.0.0.1:8765)
Port 127.0.0.1:8765: In use
Daemon service: Running (launchd)
Process ID: 12345
Gateway server: Reachable at http://127.0.0.1:8765/health
  Status: healthy
  Uptime: 3600.5 seconds
  Agents: 2
  Sessions: 1
  Clients: 3
  Channels: 2 configured

PID Lock Unavailable (Windows)

$ praisonai-bot gateway status --port 18789
PID lock status: Unavailable (kill returned a result with an exception set)
Gateway Status: healthy
  Uptime: 11.4s
  Agents: 1
  Sessions: 0
  Clients: 0

On Windows, os.kill(pid, 0) can raise SystemError. From PraisonAI ≥ v4.6.141 the PID-lock inspection is advisory only — this line replaces Gateway PID lock: … / Port …: … when the check fails, and the /health probe still runs so you still see the real status.

Daemon Issues

$ praisonai gateway status
Daemon service: Installed but not running (launchd)
Gateway not reachable at http://127.0.0.1:8765/health

Not Installed

$ praisonai gateway status --daemon-only
Daemon service: Not installed (systemd)

Platform Support

Gateway CLI works across platforms with native daemon integration:

Platform	Service Type	Log Location	Management
macOS	LaunchAgent (`ai.praison.bot`)	`~/.praisonai/logs/bot-stderr.log`	`launchctl kickstart -k gui/$(id -u)/ai.praison.bot`
Linux	systemd user service (`praisonai-bot`)	`journalctl --user -u praisonai-bot`	`systemctl --user restart praisonai-bot`
Windows	Scheduled Task (`PraisonAIGateway`)	Windows Event Log	`schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway`

Each generated unit stops (not restarts) on the gateway’s fatal-config exit code (78, EX_CONFIG) — systemd via RestartPreventExitStatus=78, launchd via KeepAlive/ThrottleInterval, Windows via a .cmd wrapper that maps 78 to a clean exit. See Gateway Exit Codes.

Configuration Files

agents.yaml
gateway.yaml

# Simple agent configuration
agent:
  name: "support"
  instructions: "You are a helpful support agent"
  model: "gpt-4o-mini"
  tools:
    - search_web
  memory: true

# Multi-bot configuration
identity:
  enabled: true                       # one session per paired user across channels (#3020)
  store: ~/.praisonai/identity.json   # optional; ~ expanded, `path:` accepted as alias

# Opt into the pre-2026-07-31 warn-and-continue behaviour permanently.
# Omit (or set true) to fail fast on any unresolved tool at start (#3553).
strict_tools: false

agents:
  support:
    instructions: "You are a support agent"
    model: "gpt-4o-mini"
  sales:
    instructions: "You are a sales agent"
    model: "claude-3-5-sonnet-20241022"

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    routing:
      default: support
  discord:
    token: "${DISCORD_BOT_TOKEN}"
    routing:
      default: sales
  slack:
    # Secret-reference form: read from a mounted file / secret manager
    # instead of plaintext or a process-wide env var.
    token: { source: file, id: /run/secrets/slack_token }
    app_token: { source: exec, id: "vault read -field=token secret/slack" }
    routing:
      default: support

See Secret References for the full { source, id } form on token, app_token, and verify_token.

Common Patterns

Diagnose → repair → verify

Inspect first, repair only if needed, then confirm the gateway came back healthy.

praisonai gateway doctor          # read-only report
praisonai gateway doctor --fix    # apply safe repairs, then re-validate
praisonai gateway status --deep   # per-channel rows + reload state

Zero-downtime posture change

restart drains in-flight turns for the given window, then relaunches — replaying the launch posture saved in ~/.praisonai/gateway.start.<host>.<port>.json, so the process comes back with the same flags it was started with.

praisonai gateway restart --drain-timeout 60

Add an inbound trigger

praisonai gateway hooks add gmail --agent triage-agent --deliver-to slack:C123
praisonai gateway hooks list

Best Practices

Use daemon-only for health checks

Use --daemon-only flag when monitoring daemon status in scripts or CI/CD pipelines to avoid gateway connection attempts.

Check logs for troubleshooting

Always check praisonai gateway logs when the daemon is running but gateway is unreachable - this reveals startup errors.

Test channel configuration

Use praisonai gateway send to test channel bot configuration before deploying to production environments.

Monitor daemon status regularly

Set up monitoring that runs praisonai gateway status --daemon-only to detect service failures quickly.

Set a runtime flag once — every restart replays it

Stop, restart with the new flag once, and every subsequent praisonai gateway restart replays it automatically — ~/.praisonai/gateway.start.<host>.<port>.json is your on-host record of what the process was launched with. To reset, delete the artefact.

Reset to YAML defaults by deleting the artefact

rm ~/.praisonai/gateway.start.<safe_host>.<port>.json before the next restart to revert to the YAML defaults (or an empty CLI baseline). A corrupt or unreadable artefact is treated as absent — the restart falls back to explicit flags and defaults.

Gateway Server

Gateway architecture and configuration

Config Discovery

Where every gateway command looks for the config when --config is omitted

Troubleshooting

Common gateway issues and solutions

Secret References

Load credentials from files, env vars, or secret managers

Cross-Platform Sessions

--identity-store — one session per user across channels

Route Bindings

Fail-fast validation — route/binding typos caught at config load

Exit Codes

Exit 78 from the strict tool pre-flight — do-not-restart contract

Tool Resolution

Core-resolver PRAISONAI_STRICT_TOOLS — complementary to this start-time gate

​How It Works

​Quick Start

​Commands

​Which verb do I need?

​Gateway Management

​Daemon Service

​Channel Control

​Inbound Hooks

​Testing & Debugging

​Diagnostics

​Command Reference

​Config discovery

​start with no config

​doctor / test / status / send / channels

​Version validation

​What the user sees

​Pre-flight credential check

​Examples

​Credential availability (without revealing values)

​Weak-secret check

Weak Secret Guard

​Auto-repair with --fix

​Pre-flight gate on start

​Route/binding target check

​Corporate CA bundle (SSL-inspecting networks)

​Token resolution

​Per-channel timeout

​Exit codes

​When to use which

​Pre-flight tool check

​Strict mode (default) — fail fast

​Non-strict — warn and continue

​“Did you mean?” mechanics

​Precedence

​Env loading

​Exit code

​Environment Variables

​Supervisor exit codes

​Single-Instance Enforcement

​PID-Lock Status Reference

​Restart the Gateway

​Options

​Persisted start-flags artefact

​Advanced: OS-native restart

​Status Output Examples

​Healthy Gateway

​PID Lock Unavailable (Windows)

​Daemon Issues

​Not Installed

​Platform Support

​Configuration Files

​Common Patterns

​Diagnose → repair → verify

​Zero-downtime posture change

​Add an inbound trigger

​Best Practices

​Related

Gateway Server

Config Discovery

Troubleshooting

Secret References

Cross-Platform Sessions

Route Bindings

Exit Codes

Tool Resolution

How It Works

Quick Start

Commands

Which verb do I need?

Gateway Management

Daemon Service

Channel Control

Inbound Hooks

Testing & Debugging

Diagnostics

Command Reference

Config discovery

`start` with no config

`doctor` / `test` / `status` / `send` / `channels`

Version validation

What the user sees

Pre-flight credential check

Examples

Credential availability (without revealing values)

Weak-secret check

Auto-repair with `--fix`

Pre-flight gate on start

Route/binding target check

Corporate CA bundle (SSL-inspecting networks)

Token resolution

Per-channel timeout

Exit codes

When to use which

Pre-flight tool check

Strict mode (default) — fail fast

Non-strict — warn and continue

“Did you mean?” mechanics

Precedence

Env loading

Exit code

Environment Variables

Supervisor exit codes

Single-Instance Enforcement

PID-Lock Status Reference

Restart the Gateway

Options

Persisted start-flags artefact

Advanced: OS-native restart

Status Output Examples

Healthy Gateway

PID Lock Unavailable (Windows)

Daemon Issues

Not Installed

Platform Support

Configuration Files

Common Patterns

Diagnose → repair → verify

Zero-downtime posture change

Add an inbound trigger

Best Practices

Related