Local (Terminal) Channel

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

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()

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: ">>> "

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

channels: local: {} is legal without a token:. The local channel is on the gateway’s token-free allowlist (email, agentmail, signal, local), so it starts cleanly at launch and after a gateway reload — the config validator never marks it degraded for a missing token. See Degraded Channel Isolation.

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?

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.

Python adapter class

The capability flags a local channel declares

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.

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.

Gateway Session Continuity

Cross-Platform Mirror

`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")

Proactive Delivery

Scheduler Delivery

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.

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.

Gateway & Control Plane

The gateway the local channel joins

Channels Gateway

Connect agents to every built-in channel

Multi-Channel Bots

Run local + remote channels together

Bot Chat Commands

/status, /new, /help, /stop

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Local (Terminal) Channel

Quick Start

User Interaction

How It Works

When does it exit?

Built-in Commands

Configuration Options

Capabilities

Trust Model

Cross-Channel Continuity

`deliver="local"` — routing outbound to the terminal

Common Patterns

Best Practices

Gateway & Control Plane

Channels Gateway

Multi-Channel Bots

Bot Chat Commands

​Quick Start

​User Interaction

​How It Works

​When does it exit?

​Built-in Commands

​Configuration Options

​Capabilities

​Trust Model

​Cross-Channel Continuity

​deliver="local" — routing outbound to the terminal

​Common Patterns

​Best Practices

​Related

Gateway & Control Plane

Channels Gateway

Multi-Channel Bots

Bot Chat Commands

Quick Start

User Interaction

How It Works

When does it exit?

Built-in Commands

Configuration Options

Capabilities

Trust Model

Cross-Channel Continuity

`deliver="local"` — routing outbound to the terminal

Common Patterns

Best Practices

Related