Aurélio Sync & Conscience Upgrade / Upgrade Réplica Conscience (push) Has been cancelled

Details

feat(telminal): add hardened Terminal-in-Telegram bot to aurelio

Port fristhon/telminal (MIT) into the aurelio monorepo as a self-hosted
Telegram shell bot for the fleet gateway (CT-217).

- telminal/ package: config (env + state file, refuses empty admins),
  core orchestrator (event handlers, router, watchers, interactive mode,
  file up/download, xterm.js image render), process (pexpect PTY + streaming
  + inline control buttons), telegram (Telethon wrapper, swappable for tests),
  cli (entry point reading TELEGRAM_* env), utils, values.
- aurelio hardening vs upstream: no first-run random token auth (explicit
  admin allowlist required); cd sandbox validated against working root;
  secrets from env mirroring the CT-217 gateway .env.
- 35 real tests (pty capture/control-char, router, watchers, perms, sandbox,
  fake-client orchestration) -- all green.
- deployment: systemd/telminal.service, .env.example entries, README, AGENTS.md.

Verified: pytest 35 passed; CLI refuses start with missing env / no admins.

2026-07-15 23:41:44 +01:00

1.7 KiB

Raw Blame History

telminal — Agent Guide

Self-hosted Terminal-in-Telegram bot for the Portugal Futurista fleet. It is a hardened re-implementation of fristhon/telminal (MIT), giving an admin allowlist a sandboxed shell on the gateway host (CT-217) from Telegram.

What it does

Runs /bin/bash -c <cmd> in a pty (pexpect), streams output to Telegram with inline control buttons (Info / Enter / Interactive / Terminate / HTML), supports interactive mode (^c = Ctrl-C), !get/upload file transfer, and !watch watcher tasks. Optional xterm.js screenshot output via pyppeteer.

Hardening vs upstream

No first-run random token auth — admins come from an explicit allowlist (TELEGRAM_ADMINS env, persisted in config.json). Refuses to start empty.
cwd sandbox: cd is validated against the configured working root; escapes are rejected.
Secrets from env (TELEGRAM_API_ID/HASH/TOKEN), mirroring the Hermes gateway .env on CT-217.

Layout

cli.py (entry) → config.py (Config) → core.py (orchestrator) → process.py (PTY) + telegram.py (Telethon wrapper) + utils.py/values.py.

Run

. .venv/bin/activate
TELEGRAM_API_ID=.. TELEGRAM_API_HASH=.. TELEGRAM_TOKEN=.. TELEGRAM_ADMINS=123 python -m telminal

Deploy via systemd/telminal.service on CT-217 (secrets from /home/hermes/.hermes/.env, working dir /home/hermes/telminal-workspace).

Tests

pytest -q   # pty, router, watchers, perms, sandbox, fake-client orchestration

The orchestrator talks to Telegram only through telegram.Telegram, so tests use a fake client — no network needed. The live Telegram end-to-end run is verified on CT-217 by the operator.

1.7 KiB Raw Blame History