Terminal-to-terminal via Telegram protocol (SSH alternative)

[dcolinmorgan]

Concept

Use Telegram Bot API as an encrypted transport layer between terminals — bypassing SSH, firewalls, and VPNs entirely.

Machine A (any terminal)          Machine B (herdr agents)
  herdr-tg shell phoenix-api        relay + telegram bot
       |                                  |
       v                                  v
  Telegram Bot API (encrypted)     Bot receives message
       |                                  |
       v                                  v
  Bot sends to relay              herdr pane send-text
       |                                  |
       v                                  v
  Bot reads pane output           Terminal executes
       |                                  |
       v                                  v
  Prints to stdout                Bot sends output back

Why

• Works through ANY firewall (only outbound HTTPS needed)
• Zero config — no SSH keys, no port forwarding, no VPN
• Already encrypted (Telegram MTProto)
• Works from a phone (just type in the chat)
• The relay + bot infrastructure already exists in this repo

Proposed CLI tool: herdr-tg

A lightweight shell script (~50 lines) that talks to the Telegram Bot API directly:

# One-shot command
herdr-tg send phoenix-api "npm test"

# Read last output
herdr-tg read phoenix-api

# Interactive shell (read-eval loop)
herdr-tg shell phoenix-api

Interactive mode

$ herdr-tg shell phoenix-api
Connected to phoenix-api via Telegram relay.
phoenix-api> ls src/
[waiting...]
src/index.ts
src/utils.ts
src/routes/

phoenix-api> npm test
[waiting...]
PASS - 42 tests passed

phoenix-api> exit

Implementation

1. herdr-tg CLI sends messages via curl to https://api.telegram.org/bot$TOKEN/sendMessage
2. Bot (already running) receives the message, parses it as a /send command
3. Bot sends text to the pane via relay WebSocket
4. For reads: herdr-tg polls getUpdates or uses a dedicated /readback flow
5. Output printed to local stdout

Alternative: Direct bot-to-bot (skip chat)

Instead of going through the chat UI, herdr-tg could use a dedicated "control channel" — the bot sends output to itself via a private channel, and the CLI tool polls that channel.

Limitations vs SSH

Feature	SSH	herdr-tg
Latency	~50ms	~1-2s
Interactive (vim, etc)	Yes	No (no PTY)
File transfer	scp/sftp	No (text only)
Streaming output	Yes	Poll-based
Port forwarding	Yes	No
Auth	SSH keys	Telegram bot token
Firewall bypass	Needs port 22	Only HTTPS outbound
Works from phone	No	Yes (just type)

Good for

• Quick commands and checks from anywhere
• Approving/responding to blocked agents
• Running scripts on remote machines
• Environments where SSH is blocked (corporate firewalls, mobile)
• Emergency access when VPN is down

Not suitable for

• Interactive TUI applications (vim, htop)
• Streaming large log output
• File transfers
• Low-latency requirements

Prior art

• teleconsole — terminal sharing via HTTPS
• Mosh — UDP-based mobile shell (but still needs a port)
• Eternal Terminal — persistent SSH (still needs port 22)

Effort

Small — the relay and bot already handle send_text, send_keys, and read_pane. The CLI tool is just a curl wrapper with a read loop. Estimated ~50 lines of shell + optional Python for the interactive mode.