Local (Terminal) Channel

Chat with your gateway agent from your own terminal — no tokens, no webhooks, no allowlist

The local channel lets you talk to your gateway agent from your own terminal — the same live session your Telegram or Discord users reach.

Quick Start

1. One command (CLI)

   The quickest way to try the local channel — no Python, no token:

   praisonai bot run --platform local

   Fields declared by the channel’s descriptor are also CLI flags — e.g. praisonai bot run --platform local --prompt "me> ". bot run starts any registered platform by name. See praisonai bot run for the full flag list.

2. Chat in two lines

   The local channel is owner-trusted — no token, no webhook, no setup.

   from praisonaiagents import Agent
   from praisonai_bot.bots import BotOS
   
   agent = Agent(name="assistant", instructions="Be helpful")
   BotOS(agent=agent, platforms=["local"]).run()

3. Custom prompt

   Set your own input prompt in Python or gateway.yaml.

   from praisonaiagents import Agent
   from praisonai_bot.bots import BotOS
   
   agent = Agent(name="assistant", instructions="Be helpful")
   BotOS(agent=agent, platforms={"local": {"prompt": ">>> "}}).run()

   # gateway.yaml
   channels:
     local:
       prompt: ">>> "

4. Terminal + remote in one process

   One process, two surfaces, one shared session — chat locally while Telegram users reach the same agent.

   # gateway.yaml
   channels:
     local: {}
     telegram: { token: "${TELEGRAM_BOT_TOKEN}" }
   agents:
     assistant:
       instructions: "You are a helpful assistant."

   praisonai-bot gateway start

User Interaction

Type a line, get a reply. Ctrl-D exits cleanly; built-in commands start with /.

$ praisonai-bot gateway start
Local channel reading from stdin (Ctrl-D to exit; /stop cancels the current run)
you> hi
Hello! How can I help?
you> /status
Bot: assistant · channel: local · uptime: 12s · running
you> /new
Session reset. Send a message to start a new conversation.
you> ^D
Local channel stopped
$

The terminal also survives a config reload — a gateway reload keeps the local channel healthy instead of dropping it into a degraded state:

$ praisonai-bot gateway reload
INFO  Channel 'local' hot-reloaded (token-free)
you> still here?
Yes, still here.

How It Works

Each line of stdin becomes one agent turn through the shared BotSessionManager, and the reply is written to stdout.

The read loop runs on a dedicated daemon thread so other channels keep running while it waits for input.

When does it exit?

Built-in Commands

Configuration Options

The local channel is token-free and declares a single config field.

Constructor kwargs on LocalBot: token="" (unused, kept for parity), agent, config, prompt.

Capabilities

The local channel declares a TTY-honest capability set so shared engines degrade correctly.

The channel’s system_prompt_hint tells the agent about these constraints: “You are replying in a local terminal: keep replies plain text; there is no markdown rendering, no message editing and no rate limit.”

Trust Model

The local operator is owner-trusted: it bypasses pairing and allowlists because it’s your own machine — which is why no token is needed. Remote channels, by contrast, require pairing before a stranger can talk to your agent.

• local is on the gateway’s token-free allowlist (email, agentmail, signal, local) — a local channel without a token: is fully healthy, not degraded, both at launch and after hot reload.

The terminal maps to a stable local-operator user id and local chat id, so it resolves to one durable session across restarts.

Cross-Channel Continuity

A message begun in the terminal continues on a remote platform under one resolved session id via the shared identity resolver and delivery router.

deliver="local" — routing outbound to the terminal

Any scheduled job, hook, or agent tool that emits deliver="local:local" writes to the terminal exactly like deliver="telegram:12345" writes to Telegram.

await botos._delivery_router.deliver("local:local", "proactive-ping")

Common Patterns

1. Dev / smoke-test a gateway agent before wiring any remote channel.
2. Single-user personal agent on your own box — no bot registration.
3. Start-here, continue-there — chat locally at your desk, keep the same session going from your phone via Telegram.
4. Proactive terminal notice — a scheduled job that pings deliver="local:local" prints straight into the operator’s terminal.

Best Practices

Related