Shell Execution on Bots

Turn any channel bot into a shell-capable agent with per-platform approval routing — one YAML flag

Flip one YAML flag and any inbound channel bot can run shell commands, with approval routed to the platform of your choice.

Before this feature, adding execute_command to an inbound bot meant building the agent, attaching an approval backend, and lifting the default deny — all in Python. Now the operator flips one flag and the gateway wires everything at bot construction.

Quick Start

1. Turn it on

   Add allow_shell: true to any channel. On a loopback-bound gateway with a single-operator DM, auto-approve every command:

   gateway:
     bind_host: "127.0.0.1"
   
   channels:
     slack:
       token: "${SLACK_BOT_TOKEN}"
       app_token: "${SLACK_APP_TOKEN}"
       allow_shell: true
       auto_approve_shell: true   # kept: loopback bind + no group_policy

   Start the gateway:

   praisonai gateway start

   Now @your-bot run ls executes on the server.

2. Require approval for real workloads

   Turn off auto-approve and route the prompt to the owner. Every shell call now sends a Slack Block Kit approval message to UOWNER, and only UOWNER can approve:

   channels:
     slack:
       token: "${SLACK_BOT_TOKEN}"
       app_token: "${SLACK_APP_TOKEN}"
       allow_shell: true
       auto_approve_shell: false
       approval_channel: "UOWNER"
       approval_users: "UOWNER"

Exposure-aware auto-approval

auto_approve_shell: true runs every shell call immediately only when the gateway is loopback-bound and the channel is a single-operator DM. On any exposed or multi-user surface it is silently downgraded to an approval backend — the exact wiring auto_approve_shell: false produces.

This mirrors the gateway auth token’s “calibrated by exposure” posture (assert_external_bind_safe): blanket auto-approve is only trusted where a single operator reaches the bot over loopback.

Even with auto-approval, a bot-exposed execute_command does not see OPENAI_API_KEY, GATEWAY_AUTH_TOKEN, or other _TOKEN/_SECRET/*_PASSWORD names in its environment, so env or echo $… cannot print them — the shell tool strips them from the subprocess env. See Credential Environment Variables.

Behaviour matrix

The downgrade routes through the same approval-backend precedence documented under Choosing an approval_mode (Slack / Telegram / Discord / HTTP / gateway → fail-closed CallbackBackend). No new backend, no new precedence — only the trigger changes. Watch for this WARN line in gateway logs:

Channel 'slack' enables shell on an exposed/multi-user surface;
downgrading auto_approve_shell to require approval. Set
auto_approve_shell_acknowledge_exposed: true to keep blanket auto-approval.

Configurations

gateway:
  bind_host: "127.0.0.1"

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: true   # kept: loopback bind + no group_policy

gateway:
  bind_host: "0.0.0.0"

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: true   # silently becomes "approval required"
    # WARN in gateway log:
    #   Channel 'slack' enables shell on an exposed/multi-user surface;
    #   downgrading auto_approve_shell to require approval. Set
    #   auto_approve_shell_acknowledge_exposed: true to keep blanket auto-approval.

gateway:
  bind_host: "0.0.0.0"

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: true
    auto_approve_shell_acknowledge_exposed: true   # I accept the RCE surface

Configuration Options

Nine per-channel fields control shell execution and approval routing.

auto_approve_shell accepts string truthy values "1", "true", "yes", "on" (case-insensitive).

Choosing an approval_mode

Pick the backend that matches where you want to answer approval prompts.

The routing precedence, exactly as wired at bot construction:

approval_mode == "gateway"                → GatewayApprovalBackend()
approval_mode == "http"                   → HTTPApproval(host, port)
approval_mode == "webhook" OR
  approval_webhook_url is set             → WebhookApproval(webhook_url)
                                             ↳ webhook mode with NO url:
                                               warn + fall through to gateway
channel_type == "slack"    + resolved id  → SlackApproval(...)
channel_type == "telegram" + resolved id  → PresentationApprovalBackend(target=chat_id)
channel_type == "discord"  + resolved id  → DiscordApproval(...)
GatewayApprovalBackend importable         → GatewayApprovalBackend()  (fallback)
otherwise                                 → CallbackBackend (deny shell tools)
                                            + warning log

On timeout, the Slack / Telegram / Discord card edits to “⌛ Timed out — not run” instead of “❌ Denied”. The auto-wired GatewayApprovalBackend() above has no notify_url, so it sends no webhook; only a backend you build yourself with notify_url also sends a follow-up {"status": "timed_out", ...} POST — see GatewayApprovalBackend webhook payload.

Fail-closed behaviour

When auto_approve_shell: false is set but no approval backend can be wired, shell commands are denied instead of silently auto-approved.

apply_bot_smart_defaults() may install an AutoApproveBackend when auto_approve_tools is on. If the shell wiring then finds no SlackApproval / PresentationApprovalBackend / DiscordApproval / GatewayApprovalBackend / HTTPApproval / WebhookApproval, leaving that backend in place would auto-approve shell despite the explicit opt-out. The gateway now swaps in a deny-by-default CallbackBackend.

If the gateway cannot determine its bind interface (host unresolvable), the exposure check also fails closed and blanket auto-approve is downgraded to require approval.

The warning line to watch for at startup:

allow_shell with auto_approve_shell=false needs approval_channel,
approval_mode (gateway|http|webhook), or a custom approval backend on the agent
— shell commands will be denied until one is configured

With routing rules

Routing rules on a shell-enabled channel keep execute_command — routed agents are shell-enabled too, not just the default channel clone.

Previously a routing rule swapped in a raw agent that never saw enable_shell_tools(), so execute_command disappeared for any turn that hit a routing rule — even with allow_shell: true. The gateway now re-applies the channel’s shell setup to routed agents, and runs the full smart-defaults pipeline first.

What allow_shell changes on the agent

Setting the flag runs enable_shell_tools() on the per-channel cloned agent, after smart defaults are applied.

The five side effects, in order:

Per-platform routing

Each platform resolves the approval target from a fallback chain, then builds its native backend.

approval_users accepts a comma-separated string or a list. An empty allowlist passes allowed_approvers=None to the platform backend, whose native default lets anyone in the channel approve.

Environment Variables

Every fallback the feature reads, in one place.

Recipes

Copy-paste-ready configurations for common setups.

gateway:
  bind_host: "127.0.0.1"

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: true

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: false
    approval_channel: "UOWNER"
    approval_users: "UOWNER"

channels:
  whatsapp:
    allow_shell: true
    auto_approve_shell: false
    approval_mode: gateway

gateway:
  bind_host: "127.0.0.1"           # loopback: Slack blanket auto-approve stays

channels:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    allow_shell: true
    auto_approve_shell: true          # kept only on loopback + non-group DM

  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    allow_shell: true
    auto_approve_shell: false
    approval_channel: "123456789"     # owner chat ID

  whatsapp:
    allow_shell: true
    auto_approve_shell: false
    approval_mode: gateway            # queue in control plane

  discord:
    token: "${DISCORD_BOT_TOKEN}"
    allow_shell: true
    auto_approve_shell: false
    approval_mode: webhook
    approval_webhook_url: "https://hooks.example.com/approve"

HTTP dashboard approvals

Serve a built-in approval page and answer from the browser.

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    allow_shell: true
    auto_approve_shell: false
    approval_mode: http
    approval_http_host: "0.0.0.0"     # default "127.0.0.1"
    approval_http_port: 9000          # default 8899

User Flow

A Slack workspace owner wants their support team to type @bot run pytest -q and see results in-thread, but only after they personally approve each command. They edit gateway.yaml on the server, add allow_shell: true, auto_approve_shell: false, and approval_channel: "UOWNER" to their slack: block, then restart the gateway. From that moment, every shell request from any Slack user triggers a Block Kit approval prompt in the owner’s DMs — they tap Approve and the command runs; they tap Deny and the agent replies “That command needs approval and was denied.” No Python was written.

Troubleshooting

Best Practices

Related