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
- One command (CLI)
The quickest way to try the local channel — no Python, no token:
bash praisonai bot run --platform localFields declared by the channel’s descriptor are also CLI flags — e.g.
praisonai bot run --platform local --prompt "me> ".bot runstarts any registered platform by name. Seepraisonai bot runfor the full flag list. - Chat in two lines
The local channel is owner-trusted — no token, no webhook, no setup.
python from praisonaiagents import Agent from praisonai_bot.bots import BotOS agent = Agent(name="assistant", instructions="Be helpful") BotOS(agent=agent, platforms=["local"]).run() - Custom prompt
Set your own input prompt in Python or
gateway.yaml.python from praisonaiagents import Agent from praisonai_bot.bots import BotOS agent = Agent(name="assistant", instructions="Be helpful") BotOS(agent=agent, platforms={"local": {"prompt": ">>> "}}).run()yaml # gateway.yaml channels: local: prompt: ">>> " - Terminal + remote in one process
One process, two surfaces, one shared session — chat locally while Telegram users reach the same agent.
yaml # gateway.yaml channels: local: {} telegram: { token: "${TELEGRAM_BOT_TOKEN}" } agents: assistant: instructions: "You are a helpful assistant."bash 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.Testing / CI — Offline Harness
The local channel doubles as a credential-free, network-free test harness for a full bot turn. Pass any file-like stdin/stdout to drive the real hook → command → session → send path and assert the reply.
import asyncio
import io
from praisonaiagents import Agent
from praisonai_bot.bots import LocalBot
agent = Agent(name="assistant", instructions="Be helpful")
out = io.StringIO()
bot = LocalBot(
agent=agent,
stdin=io.StringIO("What's 2+2?\n"), # one turn, then EOF
stdout=out,
)
asyncio.run(bot.start()) # returns at EOF
assert "4" in out.getvalue() # real reply, real pipelineWhat runs, end to end:
MESSAGE_RECEIVEDhook- Built-in command dispatch (
/help,/status, …) BotSessionManager.chat— the shared session, identity resolver, and admission ladderMESSAGE_SENDING/MESSAGE_SENThookssend_message→ yourstdout
No channel token is needed, and sys.stdin / sys.stdout are never monkey-patched. The input prompt (you> ) is written to the same stdout, so assert with in rather than equality.
The agent still calls its own model. For a fully offline run, swap the LLM for ScriptedModel from Offline Testing — the two features compose directly.
import asyncio
import io
from praisonaiagents import Agent, ScriptedModel
from praisonai_bot.bots import LocalBot
model = ScriptedModel(["4"])
agent = Agent(instructions="You are a math bot.", llm=model)
out = io.StringIO()
bot = LocalBot(agent=agent, stdin=io.StringIO("What's 2+2?\n"), stdout=out)
asyncio.run(bot.start())
assert "4" in out.getvalue()Which mode should I use?
| Scenario | How to run LocalBot |
|---|---|
| Chatting at your own terminal | BotOS(agent=agent, platforms=["local"]).run() — defaults use sys.stdin/sys.stdout |
| Scripted demo / recorded transcript | LocalBot(agent=agent, stdin=io.StringIO("..."), stdout=open("transcript.txt", "w")) |
| Unit test / CI assertion | LocalBot(agent=agent, stdin=io.StringIO("..."), stdout=io.StringIO()) + ScriptedModel for a fully offline run |
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?
| Signal | Behaviour |
|---|---|
Ctrl-D / EOF | Clean end of the terminal session |
/stop | Cancels the current agent run, keeps the read loop alive |
/new | Resets the local session; next line starts a new conversation |
| Blank line | Ignored |
Built-in Commands
| Command | Description |
|---|---|
/status | Show bot status and info (agent, uptime, running) |
/new | Reset conversation session |
/help | Show the help message (including any custom commands) |
/stop | Cancel the current agent run |
Configuration Options
The local channel is token-free and declares a single config field.
| Option | Type | Default | Description |
|---|---|---|---|
prompt | str | "you> " | Terminal input prompt |
Constructor kwargs on LocalBot: token="" (unused, kept for parity), agent, config, prompt, stdin, stdout.
Two of those are Python-constructor-only — they are not gateway.yaml fields:
| Kwarg | Type | Default | Description |
|---|---|---|---|
stdin | file-like | None → sys.stdin | Where the read loop reads lines from. Any object with a .readline() method works (io.StringIO, a pytest fixture, a pipe). |
stdout | file-like | None → sys.stdout | Where the prompt and outbound replies are written. Any object with .write() + .flush() works. |
When left as None, the fallback to sys.stdin / sys.stdout is looked up on each call, not cached at construction — so swapping sys.stdout after building the bot is still picked up.
Capabilities
The local channel declares a TTY-honest capability set so shared engines degrade correctly.
| Capability | Value | Why |
|---|---|---|
supports_edit | False | A printed TTY line is not edited in place; streaming falls back to plain appends |
supports_typing | False | No “typing…” indicator in a terminal |
needs_rate_limit | False | No provider quota to respect |
accepts_webhooks | False | Pull-based, not push |
supports_media | False | Text only |
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.”
How capabilities drive uniform chunking, streaming, and rate limiting
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.
localis on the gateway’s token-free allowlist (email,agentmail,signal,local) — alocalchannel without atoken: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
- Dev / smoke-test a gateway agent before wiring any remote channel.
- Single-user personal agent on your own box — no bot registration.
- Start-here, continue-there — chat locally at your desk, keep the same session going from your phone via Telegram.
- Proactive terminal notice — a scheduled job that pings
deliver="local:local"prints straight into the operator’s terminal. - Offline harness in tests/CI — assert that a real bot turn (hook → session → agent → send) produces the expected reply, with no token, no network, and no
sysmonkey-patching.
Best Practices
Prefer gateway start for cross-channel continuity
praisonai-bot gateway start joins the gateway’s live multiplexed session, identity resolver, and delivery router. praisonai chat runs a separate process with a separate session and does not.
Use /new to reset — not restart
Resetting the session is cheaper than restarting the process, and any other running channels stay live.
Keep replies plain text in local-only agents
A TTY has no markdown rendering. If you also serve remote channels from the same agent, the system_prompt_hint already tells the agent this.
Ctrl-D is the clean way to exit
The read loop is intentionally not supervised (supervised_inbound = False), so EOF ends cleanly and the process exits without a reconnect storm.
Prefer injected streams over monkey-patching sys
Tests that reassign sys.stdin/sys.stdout leak into the rest of the process (and other tests). The stdin/stdout kwargs give you the same reach into the read-and-write path without that cost — a cancelled test cannot leave the process in a half-swapped state.