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

# Golden Path: Agent → Gateway → Channel → Sandbox

> One runbook to go from install to a live channel reply and a sandboxed command in under 30 minutes

Go from `pip install` to an agent that replies on a messaging channel and runs code in a sandbox — with a health check that proves every piece is up.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful operations assistant.",
    sandbox=True,  # explicit agent.execute_code() API, isolated from the host
)

print(agent.start("Say hello in one sentence."))
print(agent.execute_code_sync("print('golden-path')").stdout)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[👤 User] -->|mention| C[💬 Channel]
    C --> G[🌐 Gateway :8765]
    G --> A[🤖 Agent]
    A --> S[📦 Sandbox]
    A -.optional.-> B[🧭 Browser Bridge :8766]
    G --> O[🖥️ Claw UI :8082]
    A -->|reply| C

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class U,A agent
    class C,G,B,O tool
    class S ok
```

The user mentions the bot in a chat; the gateway routes the message to the agent, the agent replies on the same channel, and any code it runs stays inside the sandbox.

***

## Quick Start

**1. Install**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai "praisonai-sandbox[docker]"
```

`praisonai` brings the gateway, channels, and Claw UI. The sandbox extra adds the Docker backend.

**2. Export secrets (shell only)**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY=...          # LLM provider key
export TELEGRAM_BOT_TOKEN=...      # or SLACK_BOT_TOKEN / DISCORD_BOT_TOKEN
export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32)   # required when binding beyond loopback
```

> [!WARNING]
>
> Never paste a token into `gateway.yaml`, a notebook, or a commit. Reference it with `${VAR}` — see [Secret References](https://praison.ai/docs/features/gateway-secret-references.md).

**3. Write gateway.yaml**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# gateway.yaml — placeholders only, safe to commit
agents:
  assistant:
    instructions: "You are a helpful operations assistant."
    model: gpt-4o-mini

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

**4. Start the gateway**

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

Preflight validates your model key and channel token before binding the port.

**5. Send a message**

Mention the bot in your chat. You should get a reply within a few seconds.

**6. Run a sandboxed command**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, SandboxConfig

agent = Agent(name="runner", sandbox=SandboxConfig.docker("python:3.12-slim"))
result = agent.execute_code_sync("print('golden-path')")
print(result.stdout)  # golden-path
```

**7. Verify everything**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai gateway status --deep
```

***

## Step Matrix

| Step | Action | Expected | If it fails |
| - | - | - | - |
| 1 | Install | `praisonai --version` prints | Check Python ≥ 3.10 |
| 2 | Export secrets | `env` shows the vars (never print values) | Re-export in the same shell |
| 3 | Agent | `agent.start(...)` returns text | Check the LLM key env var |
| 4 | Gateway | `GET :8765/health` → 200 | Port in use — see [Troubleshoot Gateway](https://praison.ai/docs/guides/troubleshoot-gateway.md) |
| 5 | Channel | Mention → reply | Token scopes / one poller per token |
| 6 | Sandbox | `stdout` is `golden-path` | Start the Docker daemon |
| 7 | Bridge (optional) | `connections ≥ 1` | Open the extension side panel |
| 8 | Claw UI (optional) | `GET :8082/` → 200 | Run `praisonai claw` |

***

## Health Check

Existing commands already probe each service:

| Service | Command | Default port |
| - | - | - |
| Gateway | `praisonai gateway status --deep` | 8765 |
| Gateway (full) | `praisonai gateway doctor --config gateway.yaml` | 8765 |
| Browser bridge | `praisonai browser doctor server --port 8766` | 8765 |
| Claw UI | `praisonai claw` | 8082 |

> [!NOTE]
>
> The gateway and the browser bridge **both default to port 8765**. When running both, start the bridge on another port: `praisonai browser start --port 8766`.

For CI or a single pass/fail signal, this snippet probes all three endpoints without reading any secret:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/usr/bin/env bash
# golden_path_check.sh — exit 0 only when every probe returns HTTP 200
GATEWAY_PORT=${GATEWAY_PORT:-8765}
BRIDGE_PORT=${BRIDGE_PORT:-8766}
CLAW_PORT=${CLAW_PORT:-8082}
ok=0
probe() {
  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$2")
  if [ "$code" = "200" ]; then echo "$1 ... OK (200)"; else echo "$1 ... FAIL ($2 → ${code:-no response})"; ok=1; fi
}
probe gateway        "http://127.0.0.1:$GATEWAY_PORT/health"
[ -z "$SKIP_BRIDGE" ] && probe browser_bridge "http://127.0.0.1:$BRIDGE_PORT/health"
[ -z "$SKIP_CLAW" ]   && probe claw_ui        "http://127.0.0.1:$CLAW_PORT/"
echo "exit=$ok"; exit $ok
```

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# golden_path_check.ps1
param([int]$GatewayPort = 8765, [int]$BridgePort = 8766, [int]$ClawPort = 8082)
$ok = $true
foreach ($p in @(@("gateway", "http://127.0.0.1:$GatewayPort/health"),
                 @("browser_bridge", "http://127.0.0.1:$BridgePort/health"),
                 @("claw_ui", "http://127.0.0.1:$ClawPort/"))) {
  try {
    $r = Invoke-WebRequest -Uri $p[1] -UseBasicParsing -TimeoutSec 5
    Write-Host "$($p[0]) ... OK ($($r.StatusCode))"
  } catch { Write-Host "$($p[0]) ... FAIL ($($p[1]))"; $ok = $false }
}
if ($ok) { exit 0 } else { exit 1 }
```

Expected output:

```
gateway ... OK (200)
browser_bridge ... OK (200)
claw_ui ... OK (200)
exit=0
```

***

## Environment Variables

| Variable | Purpose | Required |
| - | - | - |
| `OPENAI_API_KEY` (or another provider key) | Model calls | Yes |
| `GATEWAY_AUTH_TOKEN` | Gateway admin API auth | When bound beyond loopback |
| `TELEGRAM_BOT_TOKEN` / `SLACK_BOT_TOKEN` / `DISCORD_BOT_TOKEN` | Channel credentials | Per enabled channel |
| `DATABASE_URL` | Postgres memory | Optional — SQLite is the default |

***

## Troubleshooting

> **Gateway: connection refused**
>
> The gateway is not running or is bound to another port. Run `praisonai gateway status` and check the PID lock and port lines.

> **Gateway healthy, channel silent**
>
> `/health` shows the channel running but no reply arrives. Check the token's scopes / event subscriptions and make sure only **one** process polls the token. See [Troubleshoot Gateway](https://praison.ai/docs/guides/troubleshoot-gateway.md).

> **Sandbox: cannot connect to Docker daemon**
>
> The sandbox step is blocked even though the gateway is green. Start Docker, or pick another backend from [Sandbox Backends](https://praison.ai/docs/features/sandbox-backends.md). Never mark the step as passed when the sandbox failed.

> **Bridge: 0 connections**
>
> The bridge is up but no extension is attached. Open the extension side panel and re-run `praisonai browser doctor server --port 8766`.

***

## Best Practices

> **Keep secrets in the environment**
>
> Commit `gateway.yaml` with `${VAR}` placeholders only. For production, move to `file` or `exec` secret sources — see [Secret References](https://praison.ai/docs/features/gateway-secret-references.md).

> **Bind to loopback while testing**
>
> `127.0.0.1` keeps the admin API local. Set `GATEWAY_AUTH_TOKEN` before binding to `0.0.0.0`.

> **Re-run the health check after upgrades**
>
> Run the check after every gateway upgrade or token rotation so regressions show up immediately.

> **Use Helm for clusters**
>
> For Kubernetes, pass the auth token through chart values — see [Helm Chart](https://praison.ai/docs/features/helm-chart-gateway.md).

***

## Related

> **[Gateway CLI](https://praison.ai/docs/features/gateway-cli.md)**
>
> Start, stop, and inspect the gateway

> **[Sandbox](https://praison.ai/docs/features/sandbox.md)**
>
> Isolated code execution for agents

> **[Secret References](https://praison.ai/docs/features/gateway-secret-references.md)**
>
> Keep tokens out of config files

> **[Troubleshoot Gateway](https://praison.ai/docs/guides/troubleshoot-gateway.md)**
>
> Fix common gateway issues


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