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.

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)

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

   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)

   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

3. Write gateway.yaml

   # 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

   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

   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

   praisonai gateway status --deep

Step Matrix

Health Check

Existing commands already probe each service:

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

#!/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

# 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

Troubleshooting

Best Practices

Related