> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Config Discovery

> Where every praisonai gateway command looks for its config when --config is omitted

Every `praisonai gateway` command resolves its config through one canonical order, so `onboard`, `start`, `doctor`, `test`, `status`, `send`, and `channels` never look at different files.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Config discovery"
        Cmd[💻 gateway command] --> Resolve[🔎 resolve config]
        Resolve --> Cfg[📄 onboarded bot.yaml]
        Cfg --> Bind[✅ bind with channels]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Cmd input
    class Resolve,Cfg process
    class Bind output
```

## Quick Start

**1. Onboard once**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Writes ~/.praisonai/bot.yaml + ~/.praisonai/.env
praisonai onboard
```

**2. Start with no --config**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Discovers the onboarded file automatically — no --config needed
praisonai gateway start
# → Using gateway config: /Users/you/.praisonai/bot.yaml
```

`start` prints the file it picked before binding, so you always know which config is live.

***

## How It Works

Resolution walks a fixed precedence: an explicit `--config` always wins, then the working-dir config, then the onboarded home config, then the legacy alias.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    Start[praisonai gateway start] --> Q1{--config passed?}
    Q1 -->|Yes| Use[Use --config path]
    Q1 -->|No| Q2{./bot.yaml exists?}
    Q2 -->|Yes| UseCwd[Use ./bot.yaml]
    Q2 -->|No| Q3{~/.praisonai/bot.yaml exists?}
    Q3 -->|Yes| UseHome[Use ~/.praisonai/bot.yaml]
    Q3 -->|No| Q4{./gateway.yaml exists?}
    Q4 -->|Yes| UseAlias[Use ./gateway.yaml alias]
    Q4 -->|No| Exit[exit 78 — run praisonai onboard]

    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef stop fill:#8B0000,stroke:#7C90A0,color:#fff

    class Start start
    class Q1,Q2,Q3,Q4 check
    class Use,UseCwd,UseHome,UseAlias ok
    class Exit stop
```

| Precedence | Source | Notes |
| - | - | - |
| 1 | `--config <path>` on the CLI | Wins for every command. |
| 2 | `./bot.yaml` in the working dir | Back-compat for checked-in configs. |
| 3 | `$PRAISONAI_BOT_CONFIG` if set, else `~/.praisonai/bot.yaml` | Where `praisonai onboard` writes. Honours `$PRAISONAI_HOME`. |
| 4 | `./gateway.yaml` | Accepted alias for backward compatibility. |
| 5 | (none) | `gateway start` exits `78` with an onboard hint. |

Discovery works even without the optional `praisonai-code` package installed — the home fallback is a plain filesystem convention, not owned by any one package.

***

## Configuration Options

Two environment variables steer discovery when the defaults don't fit.

| Variable | Effect |
| - | - |
| `PRAISONAI_BOT_CONFIG` | Absolute path to the home config, used instead of `~/.praisonai/bot.yaml` at precedence 3. |
| `PRAISONAI_HOME` | Base directory for `~/.praisonai`; the home config resolves to `$PRAISONAI_HOME/bot.yaml`. |

***

## Common Patterns

### `start` with no config found

When nothing is discovered, `start` prints an actionable hint and exits `78` instead of silently starting channel-less:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ 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
```

### Single-agent mode skips channel discovery

Pass `--agents <path>` to run one agent with no channel config — discovery is skipped:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai gateway start --agents agents.yaml --port 9000
```

### Diagnostics use the same file `start` binds

`doctor`, `test`, `status`, `send`, and `channels` default `--config` to a `gateway.yaml` sentinel. Left at the default, they run the same discovery order, so a `doctor` run inspects exactly what `start` would bind:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai onboard
praisonai gateway doctor   # inspects ~/.praisonai/bot.yaml, not a missing gateway.yaml
```

***

## Best Practices

> [accordion] Onboard, then start with no flags
>
> `praisonai onboard` → `praisonai gateway start` is the happy path. `start` discovers the onboarded config and prints `Using gateway config: <path>` so you always see which file is live.

> [accordion] Check in ./bot.yaml for project-local configs
>
> A `./bot.yaml` in the working dir wins over the home config (precedence 2). Commit it to keep a project's gateway config alongside its code.

> [accordion] Point at a custom home with PRAISONAI\_BOT\_CONFIG
>
> Set `PRAISONAI_BOT_CONFIG` (or `PRAISONAI_HOME`) to run multiple onboarded profiles from one machine without passing `--config` every time.

> [accordion] Treat exit 78 as 'run onboard'
>
> An exit `78` from `start` means no config was found — run `praisonai onboard` or pass `--config`. The installed daemon units treat `78` as do-not-restart, so a missing config won't loop the service.

***

## Related

> [card] [Gateway CLI](https://praison.ai/docs/features/gateway-cli.md)
>
> Every gateway command, its flags, and the discovery order in context

> [card] [Onboarding](https://praison.ai/docs/features/onboard.md)
>
> Writes the `~/.praisonai/bot.yaml` that discovery finds

> [card] [Config Migration](https://praison.ai/docs/features/gateway-config-migration.md)
>
> Start-time `config_version` validation on the discovered config

> [card] [Exit Codes](https://praison.ai/docs/features/gateway-exit-codes.md)
>
> Exit `78` — the do-not-restart contract when no config is found


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.