Control devctrl sessions from Telegram

The optional @devctl/provider-telegram package adds a normal Telegram bot, not a Mini App. It runs in the controller. The controller and execution hosts remain online; the laptop does not need to be connected.

A paired private chat can:

The bot uses the existing controller users, session ownership, terminal byte transport and approval lifecycle. It cannot create an unscoped operator login, run an arbitrary shell, launch a provider or restart a stopped session.

Install and configure

Bundled checkouts include the optional package in the controller's dependencies. It adds no third-party SDK or mandatory dependency. A separately packaged install uses the same workflow as other optional provider packages:

pnpm --filter @devctl/controller add --save-optional /path/to/provider-telegram.tgz

Rebuild the affected control plane to discover a new package. Configure a bot only on the controller that owns the projects/users. No package, no token, a disabled bot or a Telegram outage leaves the normal controller/TUI/web sessions available. DEVCTL_MESSENGER_PROVIDER_PACKAGES is an operator-owned comma-separated package list; an empty value disables messenger discovery.

  1. Create a bot through Telegram's official @BotFather.
  2. Open Integrations → Remote interface → Telegram in either TUI or web. The legacy t shortcut in Web Access opens the same panel. A console administrator uses Add/replace bot token (k). Input is hidden; the token is stored in the existing encrypted controller keyring and never appears in workspace grants, public snapshots or serialized bot state.
  3. Enable the bot (e). devctrl verifies it with getMe, then starts long polling. Use one polling controller per bot token; an existing webhook/other poller must be removed by its owner before this consumer can use it. devctrl does not silently delete an existing webhook or configure another operator's bot.
  4. Open the displayed bot link and send /start. An unpaired chat receives only its own numeric Telegram user ID and pairing instructions, no workspace data.
  5. While signed into your own devctrl console user, select Pair my chat (p) and enter that numeric ID. Open the generated one-time link in Telegram within five minutes. Only that exact private Telegram account can redeem it.

Server users pair themselves. Only a console administrator configures the server's bot token. Each user's status shows only their own binding. Disabling a server user immediately stops their operations and notifications. Disconnecting the chat (x or /disconnect) removes its binding, pending pairing and callbacks. Other users' bindings and all running sessions remain untouched.

Replacing a token for the same bot retains pairing. Configuring a different bot identity invalidates existing bindings and requires a fresh pairing.

Use the chat

/projects opens project buttons; select a project, then a session. /sessions shows running sessions available to your user. Refresh or /view fetches the last 70 terminal lines, at most 3,200 displayed characters, with terminal controls removed. The snapshot is a view of the existing terminal, not a stored transcript or a live video stream.

Select Reply in the chosen session before sending text. The next text message is bound to that exact session; changing the selected session cannot redirect an already selected reply. /cancel cancels it. The controller sends the exact accepted UTF-8 text as bracketed paste and sends Enter separately using the same terminal input transport as TUI/web. Plain text up to 8 KB is accepted; terminal control characters are rejected. This confirms transport submission, not that the provider finished processing the request. Use View to check the response.

A TUI/browser attachment owns terminal input. Detach it before sending a Telegram reply. The bot refuses to replace an existing viewer/writer, reserves input during the short submission, then detaches its own client. It checks observed provider state and an explicit current host-agent capability; the runtime additionally requires an existing tmux session. A vanished/old provider is never launched as a side effect. Older host control planes can serve views but must be updated before bot input becomes available. Project containers do not need a toolchain rebuild for this control-plane capability.

/approvals lists pending requests. Review request shows the project, session, requested resource/purpose, each allowed action and each constraint. Checkbox buttons generate an exact selection; at least one action must remain selected. Approve selected sends those indices to the same Store.decideMcpApproval used by native/web approvals and immediately pushes its existing delivery command. Deny rejects the current request. Expired, consumed, withdrawn or already decided requests cannot be replayed through old Telegram buttons. Approval status and delivery status remain separate.

Notifications and failures

The bot checks attention/delivery state every three seconds and after polling updates. Event markers and Telegram update offsets persist across controller restarts. Old checkbox controls expire after ten minutes. Telegram rate-limit responses and server errors receive bounded backoff; API exception bodies/URLs are excluded from diagnostics. Network failures never expose the bot credential.

For prompt safety, an update is durably recorded before a side effect. Replayed Telegram updates cannot submit the same prompt/approval twice. This is at-most-once submission: if the controller dies between receipt and input transport, a message can remain unsubmitted or uncertain. devctrl does not blindly replay it; inspect the session before resending. Notification delivery can also be uncertain if the network disconnects after Telegram accepted a message; notifications contain no mutating operations themselves.

No inbound webhook or public browser tunnel is necessary. The controller requires outbound HTTPS to api.telegram.org; the phone requires Telegram connectivity. Normal Telegram bot chats are cloud chats, not Secret Chats. Terminal output and prompts sent through this optional channel are transmitted to Telegram; pair it only when that is acceptable for the selected workspaces. devctrl itself stores only scope/selection metadata, deduplication markers and encrypted bot credentials, not prompt or terminal-output content.

Limits and removal

Current support is private text chat, inline buttons and bounded terminal views. There is no Mini App, file upload/download, voice transcription, arbitrary key injection, full terminal emulation or new-session creation. Session context that requires a rich interactive terminal remains available in TUI/web. Projects, sessions and requests are paginated in groups of 20; use project selection to narrow a session list. Individual approvals use the same action/constraint limits as devctrl's permission schema (up to 20 each).

Disable the bot before uninstalling the package. Remove its stored token via the administrator settings API with { "enabled": false, "removeToken": true } sent to PUT /v1/messengers/telegram, then remove the optional package and rebuild the controller. Provider removal leaves durable devctrl sessions intact. Rotate/revoke an unwanted upstream bot token through BotFather separately.

Messaging access may be included in some inflight Wi-Fi plans. Availability and allowed applications depend on the airline, flight and connectivity plan; there is no universal free-access guarantee. For example, SWISS's official announcement includes Telegram among supported chat services; its current internet options explain that options depend on the flight and travel class.

Operator API and testing

All configuration endpoints use normal console authentication and current user scope. Bot callbacks cannot specify module paths or arbitrary console user IDs.

Method Path Purpose
GET /v1/messengers Installed optional packages and this user's masked status
PUT /v1/messengers/:id Administrator-only enable/disable and encrypted token replacement/removal
POST /v1/messengers/:id/pair Own-user one-time pairing, {externalUserId:"numeric ID"}
DELETE /v1/messengers/:id/binding Disconnect only the authenticated user's chat

The adapter uses only the official Telegram Bot API: getMe, getUpdates, sendMessage, and answerCallbackQuery. Polling offsets are persisted and callback data contains opaque server-side IDs, never credentials or permission payloads.

Tests mock all external API calls. Normal tests never contact Telegram, create a bot or send real messages. They cover exact private pairing, user ownership, select/view/reply, byte transport and separate Enter, input ownership, stopped and legacy runtime refusal, approval action/constraint selection, disabled users, revocation/consumption, deduplication, delivery notifications, credential masking, optional/no-token startup and native setup interactions.