Remote control

Remote control with Telegram

Connect a Telegram bot to Orkestra, pair your phone, and then read status, browse terminals, talk to Helm and answer approvals from Telegram.

On this page

Purpose

Connect a Telegram bot to check project and terminal status, send text to a terminal, talk to Helm, and answer approval requests from your phone. Orkestra stays running on your computer, and it asks you before risky actions.

Where to find it

  • In Orkestra: click the gear Settings button at the right of the top bar. Click Remote in the left list. This pane is the only place to set up the connection.
  • In Telegram: the chat with your bot. Type / to see the command list. Orkestra adds the list to Telegram when the connection starts.
  • Signs in Orkestra: the remote tag on a Helm chat, the Phone control badge on a terminal title bar, and the Take back control button in the terminal info menu.
  • The live terminal view — when available, ▶ Open terminal opens one terminal on your phone inside Telegram. This feature is not yet generally available: it has only been checked in a local setup, and the hosted page and support for Telegram on iOS and Android are still being prepared. The button appears only when the encrypted relay is configured, the bot username is known, and remote control is paired and not paused.
  • Telegram alerts for agents are a different feature. They live in Settings → Notifications. See Settings: the window, appearance, terminal, workbench and notifications.

What you see

Settings → Remote (top to bottom)

  • Remote control group:
    • Enable remote control — off by default. Turn it on to allow Telegram commands and remote notifications.
  • Bot token group:
    • Telegram bot token — a hidden-text field. It shows "Paste bot token". After a token is stored it shows "••••••••". Orkestra never shows the stored token.
    • Set — stores the token. After a token exists, Replace and Clear show instead. Clear removes the token.
    • Orkestra stores the token in the OS keychain. If OS encryption is unavailable, it cannot store the token.
    • A red line for a failed store or clear.
  • Pairing group — shows only after a token is stored:
    • Pair a device — click Pair to create a one-time link for your phone.
    • While Orkestra waits: the line "Open this link on your phone to pair:" with the link as plain text, the line "Waiting for pairing…" and Cancel.
    • After pairing: Paired to with the Telegram name, for example "@anna". The Unpair button removes the pairing. The line "Pairing is a draft — Apply settings to activate it." shows until you apply.
  • Inbound group:
    • Pause inbound messages — shown only after pairing. Turn it on to stop Telegram commands while keeping the pairing and outbound notifications. Turn it off to resume inbound control.
    • Connection — a dot and a word. See "States and messages".
  • Test group — shows only when a pairing exists:
    • Allowed user — the paired Telegram name.
    • Send test message — sends a test to your paired Telegram chat; the pane shows the result.
  • At the bottom of the Settings window: Reset, Cancel, Apply and OK. Switches and the pairing are drafts until you click Apply or OK. The token acts at once.

In Telegram: the bot commands (the text after the dash is the description in the Telegram menu)

  • /status — summarize the selected project's tasks, terminals, groups, worktrees and live terminal states.
  • /tasks — list tasks grouped by status, with open tasks and the completed-task count.
  • /agents — list live terminals with their agent, state and recent activity; dormant terminals appear as a count.
  • /terminals — browse workbenches and terminals. See "Browse the terminals of a project".
  • /overview — show live terminals across projects, grouped by state. ↻ Refresh reloads the card.
  • /project — choose and pin a project for this chat.
  • /stop — cancel the Helm run started by your most recent message.
  • /help — list commands and explain how to send a message to Helm.

In Telegram: cards and buttons

  • Every reply starts with the line "Project: ‹name›". A card lists up to 8 items. The buttons ‹ Previous and Next › change the page. ‹ Back goes up one level.
  • A terminal line starts with a mark: ⚠️ awaiting input, ✅ finished, ⏳ working, ▪️ no report. The state word is awaiting, finished, working, no report, error, dormant or exited.
  • A terminal card shows "Workbench", "Terminal", "State", "Freshness" and "● live" or "▪️ dormant". Its buttons: ▶ Open terminal (only when the terminal Mini App is available), 📷 1 screen, 2 screens, 4 screens, Recap, Last message, ⟳ Reconnect (dormant terminals only) and ‹ Back.
  • ▶ Open terminal opens the terminal in Telegram when a launch link is available. Links work for new and older saved terminals when the encrypted relay is configured and the bot username is known. The button is hidden while remote control is paused or the bot is not paired.

In Telegram: approval requests — a card "Approval needed" with Approve once and Deny. See Approvals.

The phone terminal view (top to bottom)

  • The head: a line "‹project› / ‹workbench›" (with " / ‹branch›" in a work branch), then the terminal name and its agent (for example "Claude Code"), and a chip that says who controls the terminal: "Desktop controls" or "Another phone controls" while this phone is read-only. When the desktop sends no project details, the head shows "Orkestra" and "Terminal" with the first 8 characters of the terminal id. While this phone controls it, the chip reads "You control this terminal" and a Release control button shows.
  • The terminal: the live screen. "Older output is not shown" shows above the first line when older history was left out. A thin bar at the right shows where you are in the history. A read-only view of a larger terminal is scaled down and shows a tag such as "120 × 40, scaled to fit".
  • The bottom area: a banner with one button (for example Take control, Retry or Reconnect), or, while this phone controls the terminal, the key bar "Terminal keys": Esc, Tab, Ctrl, ^ keys, the four arrows, Enter and Paste.
  • Some answers fill the whole page instead: a title, one sentence and one button. See "States and messages".

In Orkestra, while a person controls a terminal

  • The Phone control badge on the title bar, next to the status dot.
  • The terminal has the phone's size: the same number of columns and rows as on the phone. When that size does not fit the terminal window, Orkestra shows the terminal smaller, so that you can see all of it.
  • Take back control in the terminal info menu. See The terminal info menu.

How to

Turn on remote control and store the bot token

Before you start, get a bot token from Telegram. The pane gives no steps to create a bot.

  1. Click the gear Settings button at the right of the top bar.
  2. Click Remote in the left list.
  3. Turn on the Enable remote control switch.
  4. Click the Telegram bot token field.
  5. Paste the token.
  6. Click Set.

Result: the field shows "••••••••". Replace and Clear show. The Pairing group appears. Orkestra stored the token without Apply.

Pair your phone

Before you start, store a bot token and turn on Enable remote control.

  1. In the Pairing group, click Pair.
  2. Read the link after "Open this link on your phone to pair:".
  3. Open that link on your phone.
  4. Start the bot in the Telegram chat that opens. Do this within 90 seconds.
  5. Wait for "Waiting for pairing…" to change to "Paired to @name".
  6. Click Apply at the bottom of the Settings window.

Result: the Connection row shows "Connected". The bot sends no message to Telegram when pairing ends. Look at Orkestra to see the result.

Send a test message

Before you start, pair a device and click Apply.

  1. In the Test group, click Send test message.

Result: the pane shows "Test message sent." Your Telegram chat gets a message with the lines "Orkestra" and "Test notification from the Remote settings pane."

Pause inbound messages

  1. In the Inbound group, turn on Pause inbound messages.
  2. Click Apply.

Result: the connection stops. Orkestra ends all phone control of terminals at once. To go on, turn the switch off and click Apply.

Unpair the device

  1. In the Pairing group, click Unpair.
  2. Click Apply.

Result: the pairing is gone. Orkestra ends all phone control of terminals at once. Click Pair to pair a device again.

Choose a project in Telegram

  1. Send /project to the bot.
  2. Tap the button with the project name.

Result: the card changes to "Pinned to ‹name›." Then it shows the work branches of the project (with an ⌗ All terminals button), or the terminals when the project has no work branches. The chat keeps this project until you choose another one or Orkestra restarts.

Browse the terminals of a project

Before you start, pin a project, or let the chat follow the project that is active in Orkestra.

  1. Send /terminals to the bot.
  2. If the card is "Workbenches", tap a workbench button. It shows the name and the number of terminals.
  3. Tap a terminal button. It shows the name and the state.

Result: the terminal card opens and the terminal is selected. A project with one workbench skips step 2.

Read the output of a terminal

Before you start, open the card of the terminal.

  1. Tap 📷 1 screen, 2 screens or 4 screens.

Result: the bot sends a picture file with the name of the terminal. The caption names the project, the terminal, the screens and the source: "live screen" or "on-disk history". If the picture fails, the bot sends the last lines as a text block (48 lines for each screen). With no output it says "No terminal output is available."

Open a terminal in the Telegram Mini App

Before you start, open the terminal card. ▶ Open terminal must appear on the card; it is shown only when the link prerequisites are met and remote control is paired and not paused.

  1. Tap ▶ Open terminal.

Result: Telegram opens the terminal Mini App for that terminal. When no other phone controls the terminal, this phone takes control at once: the chip reads "You control this terminal". When another phone controls it, the page opens read-only with "Read-only. Another phone controls this terminal."; tap Take control to take it.

Get a recap or the last message of a terminal

Before you start, open the card of the terminal.

  1. Tap Recap or Last message.

Result: a toast shows "Working…". Then the bot sends "<terminal>: <text>". Recap is the recap of the terminal. Last message is a short summary of the last output.

Send text to a terminal

Before you start, open the card of a live terminal.

  1. Type a message that starts with >, then your text. For example: > npm test
  2. Send the message.

Result: the bot answers "Sent to <terminal>." Orkestra types the text into the terminal and presses Enter. It asks no question first.

Wake a dormant terminal from Telegram

Before you start, open the card of a dormant terminal.

  1. Tap ⟳ Reconnect.
  2. Tap ⟳ Reconnect on the card "Reconnect ‹name›?".

Result: a toast shows "Reconnecting…". The card then shows the new state. A > message to a dormant terminal also opens this question card.

See every live terminal

  1. Send /overview to the bot.

Result: the card lists the live terminals of all projects by group. Tap ↻ Refresh to reload it. Tap a terminal button to open its card.

Talk to Helm from Telegram

  1. Send a message that does not start with a command word and does not start with >.

Result: Helm works on it in the chat of the chosen project. The bot sends ONE reply when Helm finishes. If Helm fails, the bot sends a card that starts with "⚠️" and a ↻ Retry button. The button works for 5 minutes. Open History in the Helm header to see the chat. It has the remote tag. See Helm assistant.

Stop a Helm run

  1. Send /stop to the bot.

Result: the bot answers "Cancelled the active run." If messages wait in the queue, it also says how many it cleared.

Answer a confirmation card from Helm

  1. Read the card. A launch card starts with "⏳ Launch preview".
  2. Tap ▶ Launch or Cancel on a launch card. Tap ✅ Approve or ⛔ Deny on other cards.

Result: the card changes to "✅ Launched by you", "⛔ Cancelled by you", "✅ Approved by you" or "⛔ Denied by you".

Take control from the phone terminal view

Before you start, open the phone terminal view of a terminal that this phone does not control.

  1. Tap Take control in the banner at the bottom.
  2. Read the sheet "Take control of this terminal?".
  3. Tap Take control on the sheet.

Result: the chip reads "You control this terminal" and the key bar shows. The terminal resizes to fit the phone, and programs in it redraw. In Orkestra, the terminal changes to the phone's size too. The desktop or the other phone becomes read-only.

Release control from the phone terminal view

  1. Tap Release control in the head.

Result: the chip changes and the key bar goes away. The desktop can type again, and the terminal in Orkestra fits its window again.

Copy text from the phone terminal view

  1. Touch and hold a word on the terminal screen.
  2. Drag to extend the selection.
  3. Tap Copy.

Result: the text is on the phone's clipboard and the selection clears. When a program in the terminal uses the mouse, a touch goes to the program instead, and nothing is selected.

Take back control of a terminal

  1. Find the terminal with the Phone control badge.
  2. Click the Terminal info button, the round i icon after the terminal name.
  3. Click Take back control.

Result: control returns to you at once. The badge goes away, and the terminal fits its window again. See The terminal info menu.

States and messages

The Connection row

  • Blue dot, pulsing — "Connected". The listener runs.
  • Amber dot — "Reconnecting". Telegram refused the last request. Orkestra tries again.
  • Red dot — "Connection error". A request failed.
  • Grey dot — "Not configured — pair a device to enable inbound control", or, when a pairing exists, "Stopped — pairing pending Apply". The second text also shows when inbound is paused or remote control is off.
  • The row refreshes every 2 seconds. The listener runs only when remote control is on, a pairing is applied and inbound is not paused.

Messages in the pane

  • "Invalid token", "Token is empty after trim", "Couldn't store the token: …", "Couldn't store the token.", "Couldn't clear the token." — the token step failed.
  • "No bot token configured", "Couldn't reach the bot: …", "Bot account has no username", "Failed to begin pairing." — Pair failed.
  • "Pairing timed out — no one started the bot within 90s", "Pairing cancelled", "Pairing failed." — pairing ended without a device.
  • "Apply settings to activate this pairing." — Send test message is off until you apply.
  • "No paired device", "Failed.", "Failed to send test message." — the test failed.
  • Pair, Unpair, Replace, Clear, Set and the token field are off while Enable remote control is off.

Messages in Telegram

  • "Unknown command. Send /help for the list." — a mistyped command. A message that starts with a path, for example /usr/bin/x, goes to Helm.
  • "No active project — open the desktop app and select one first." — no project is active.
  • "Desktop is now on ‹B› (was ‹A›). Send again to continue in ‹B›." — you changed the project in Orkestra. Send the message again.
  • "Pinned project ‹name› is unavailable. Use /project to choose another project." — the pinned project is gone.
  • "Helm is busy — try again shortly." — five messages already wait. "Helm did not reply in time." — no answer after 2 minutes.
  • "Orkestra isn't running right now — open the desktop app and try again." — the message did not reach the Orkestra window.
  • "Remote control is unavailable: <engine> offers no verified non-bypass permission mode." — the Helm engine cannot run safely from Telegram. The text can also read "did not enter the verified non-bypass permission mode."
  • "Select a terminal first with /terminals." — a > message with no selected terminal.
  • "<name> is not live — reconnect it first.", "That terminal is gone: <name>.", "That terminal's session has ended: <name>." — the terminal cannot take input.
  • "Not sent to <name>. A person controls this terminal through Telegram. …" — another holder has the terminal. "Only partly sent to <name>." — part of the text arrived. Do not send it again before you look at the terminal.
  • "Expired — send /terminals again." and "Expired — send /project again." — a card is older than 5 minutes. "⏲️ Expired — auto-denied, nothing ran." — nobody answered a confirmation card in time.
  • "⚠️ Rate limit — not run." — Orkestra allows 5 approvals in one minute. A lower limit on concurrent agents lowers it. "This request is no longer pending." — the approval card is already closed.
  • "1 message that arrived while Orkestra was offline was too old to process. Send it again if you still need it." — Orkestra drops messages older than 15 minutes. The count changes for more messages.
  • "Something went wrong while handling your last message, so it was skipped. Please send it again." and "Couldn't send the full output — it was too large." — a failed step. Send the message again.

The phone terminal view

  • Chips: "You control this terminal", "Desktop controls", "Another phone controls", "Read-only", "Connecting", "Reconnecting", "Desktop offline", "Sleeping", "Exited", "Remote control paused".
  • "Waiting for the first screen" — the page waits for the first snapshot. The keys show off with "Keys turn on when the screen arrives."
  • "Read-only. The terminal is controlled on the desktop." — the desktop controls it. Take control asks first; the sheet says "The desktop becomes read-only until you release control."
  • "Read-only. Another phone controls this terminal." with "Taking control makes that phone read-only." — another phone controls it. Take control asks first; the sheet says "Whoever controls it now becomes read-only until you release control."
  • "Read-only. Someone else controls this terminal." — the page cannot tell who controls it. Take control asks first.
  • "Control returned to the desktop." — this phone was away for more than 60 seconds.
  • "Keys are off while the screen loads." — this phone controls the terminal, but a new screen is on its way. Nothing you type or paste is sent until it arrives.
  • "Connection lost. Next attempt in 4 s. This phone is read-only when it reconnects." — the page tries again by itself: 1, 2, 4, 8, then 15 seconds apart, 8 times. The last screen stays, dimmed, with "Last screen · may be out of date".
  • "Orkestra closed this view. Opening it again. This phone is read-only after it opens." — the desktop dropped this view; the page opens it again at once.
  • "Orkestra on your desktop is not reachable." with Retry — Orkestra is not running or not online. With no screen received yet, the terminal area shows "No screen yet".
  • "This terminal is sleeping." with Reconnect — a sheet asks "Reconnect this terminal?". The Reconnect action is not available yet and sends nothing. Start the terminal again in Orkestra on your desktop, then close the phone view and open it again.
  • "The process exited (code 0)." — the history stays; the terminal accepts no input.
  • "Your last input may not have arrived" with Dismiss — the connection dropped before Orkestra confirmed your last input. It was not sent again. Check the screen before you type again.
  • If a whole-page answer replaces the screen while your last input is still unconfirmed, the answer carries a note: "Your last input may not have arrived, and it was not sent again. Check the screen before you type again." When the session itself ended, the answer is "The session ended unexpectedly" with "The connection to this terminal ended before Orkestra confirmed your last input." Tap Reopen; the new view shows no note, and the input is not sent again.
  • Whole-page answers: "This terminal is not available", "Too many open views", "Orkestra on your desktop is busy", "Orkestra on your desktop needs an update", "The session ended unexpectedly" (Reopen), "This link was not accepted", "Remote access was turned off", "The desktop could not be verified", "This link is not valid", "The page could not start".
  • "The page could not start" — the page failed to start, or failed while it ran. It ends its connection first, so this phone no longer controls the terminal; tap Close and open the terminal again from the bot.
  • "Remote control is paused in Orkestra." with Check again — a banner, not a whole page: the last screen stays, dimmed. Turn remote control back on in Orkestra on your desktop, then tap Check again.
  • These answers, "This terminal is sleeping." and "The process exited" stay when the connection drops: the page does not try again by itself. Only an answer's own button (Try again, Reopen, Check again) tries again. If Orkestra on your desktop goes offline, an answer is replaced by "Orkestra on your desktop is not reachable." with Retry; a sleeping or exited terminal keeps its message.
  • Short messages at the bottom of the screen: "Not sent. This phone does not control the terminal.", "Not sent. Control is being confirmed. Try again in a moment.", "Not sent. Orkestra on your desktop did not accept the input.", "Not sent. The connection is not ready. Try again.", "Not sent. Earlier input is still on its way to the desktop. Try again in a moment.", "Not pasted. The text is larger than 32 KiB.", "Not pasted. This page cannot read the clipboard.", "Copy failed. This page cannot write to the clipboard.", "Control was not taken. Try again.", "Control was not released. Try again."

Phone control in Orkestra

  • Typing in the terminal shows the toast "A person controls this terminal through Telegram. Take back control to type here." It shows once for each hold.
  • Sleep, Wake, Reload, Close, Restart and Start new session are off. A grey button still shows its tooltip when you point at it, and a click on it does nothing. The tooltip reads "A person controls this terminal through Telegram." In the terminal info menu, the tooltip of Sleep, Wake, Reload and Close also adds "Try again in 60 seconds, then 2 minutes, then 5 minutes."
  • Idle sleep skips the terminal. When you use it from the Agents panel, the summary card counts the skip, and a short app card with a red error icon shows "A person controls this terminal through Telegram. Try again in 60 seconds, then 2 minutes, then 5 minutes." once. These cards stay for 6 seconds and wait while you point at them. See Feedback, errors and notices.

Limits and tips

  • Only the paired Telegram user in the paired chat can use the bot. Orkestra ignores everyone else and sends no reply. One device can be paired at a time.
  • Orkestra reads text messages only. Photos, voice messages and files that you send are ignored. Orkestra sends files to you: a reply longer than 4096 characters arrives as a text file (.txt) with a short caption, and a screen arrives as a picture file.
  • Helm answers in Telegram with one message. The last block of its text is the answer. Earlier steps show shortened under "Earlier in this turn:". An empty answer reads "(Helm replied with no text.)".
  • Telegram messages for one project always go to the same Helm chat of that project. A message sent while a run is active waits in a queue of 5.
  • Helm asks for your tap before it launches agents, runs input in a terminal, opens, closes or reconnects terminals, deletes or trashes items, removes worktrees, restores sessions, schedules work or renames a project. Helm cannot change settings, import, clone or delete projects, or read files from Telegram.
  • The approval card has only Approve once and Deny. The desktop dialog can offer more choices, such as Always approve. Orkestra sends the card only when remote control is on, a device is paired and inbound is not paused. A card stays open for the time of the request and then denies by itself.
  • The project pin, the selected terminal and open cards live in memory. They reset when Orkestra restarts or when you pause inbound. Cards stop working after 5 minutes.
  • A > message needs a selected terminal. Send /terminals and tap a terminal first. ‹ Back on the terminal card clears the selection.
  • When you start a sleeping terminal again on the desktop, a phone terminal view that is open on it keeps showing "This terminal is sleeping." and no new output. Close the phone terminal view and open it again: it then shows the terminal live.
  • After the phone terminal view reconnects, it can say "Read-only. Another phone controls this terminal." for up to 60 seconds, even when no other phone is open: Orkestra still counts this phone's earlier view as the holder. Tap Take control to take it back.
  • In the phone terminal view, one phone or the desktop controls a terminal at a time. A paste can be up to 32 KiB. Very fast output (for example a program that prints without a pause) can end the view on a slow phone with "The session ended unexpectedly"; tap Reopen.
  • Phone control of a terminal is a separate remote terminal view. The bot commands above never take it. The Settings window has no switch for it. It ends when you click Take back control, when the remote view is out of contact for 60 seconds, when you unpair or pause inbound, or when you turn remote control off. While a person controls the terminal, its size can follow the remote view. Orkestra tries to restore your size when control ends.
  • These two tips apply when your configured bot offers ▶ Open terminal, which opens that terminal on your phone.
    • Each pairing gives Orkestra a new key. A terminal link made before the latest pairing no longer opens the terminal; use a link made after it. What you type and what the terminal shows travel encrypted between Orkestra and your phone, so the relay in between cannot read them.
    • The terminal link on your phone uses the same proxy settings as the bot, including the NO_PROXY list; a SOCKS proxy is not supported for the link, and the link then stays offline.