Watch and steer live agent sessions

Added in v0.210.0 A live session is an agent session you can follow and steer while it runs. An agent that works on its own - a lane worker, a runner on a build machine, a terminal someone left running - regularly stops to ask something: may it run this command, which of two options, should it wait for its usage limit to reset, would someone sign it in again. Without a live view, that question sits in a terminal nobody is looking at, and the agent waits.

orboto streams every session a runner owns to your workspace: its transcript, the question it is waiting on, and its state. You answer with one tap in the browser or on your phone, type messages into the session, and take it over when you need to steer it yourself. No port is opened on the machine the agent runs on: the runner connects out to orboto over the agent WebSocket it already uses.

The page of one session is the Remote console since 0.212.0: the session as a conversation, replies, slash commands, permission answers and the pull request of what the agent changed.

How a session gets published - which runners do it, which agent tools are supported, and how to publish a session no runner owns - is on Publish an agent session live.

Where live sessions appear

Open Admin -> Agents -> Live. At the top of the tab, above the presence cards, Live agent sessions lists every session you may see while it runs. Sessions that wait for an answer come first and are marked asks you. Click a session to open its panel.

The panel shows:

• Badges: the state (Working, Waiting for you, Idle, Ended, Lost - the runner stopped reporting), the agent tool (Claude Code, Codex, Pi, Gemini, Terminal) and the model. Runner offline means the runner lost its connection; what you type waits until it reconnects.
• Transcript: the session's lines as they happen, newest at the bottom. Tool calls and tool results fold open on click. Load earlier lines pages further back.
• Takeover: who is steering the session right now, and until when.
• The agent asks: the open question with its answers.
• Composer: a message to the agent. Enter sends, Shift+Enter adds a line.

Answer the agent

The answer reaches the session within about two seconds. The question card closes as soon as orboto has accepted the answer. If someone else answered first, the card refreshes and shows what is still open. For a typed message, the line under the composer shows its delivery: Waiting for the runner, Delivered, Refused by the runner, The runner cannot take this input or Not delivered in time (a message no runner confirmed within ten minutes).

A session that runs in a plain terminal gets a Keystrokes mode instead of a message field: every key you type goes to the terminal as you press it, and the buttons Esc, Tab, the arrow keys, Ctrl-C and Enter cover the keys a phone keyboard lacks.

At the usage limit

Added in v0.230.0 The panel of a session that rotates login profiles - every orboto claude session, and a runner session started with --on-limit - has a section At the usage limit. It says what the session does when an account hits its limit - switches over every login profile, over chosen ones, asks you, stops, or only records the limit - with the threshold and the strategy of a switch, who set the policy last and when. The form beneath it changes the policy of the running session without a restart: pick the policy, tick the profiles in the order they should be tried, set the percent and the strategy, and apply. A profile added later joins a switch over every profile, and a disabled one leaves every rotation.

The form appears for the session's account, its owner, admins with admin:agents:write and people the session is shared with at Operate level, while nobody else holds the takeover. The session confirms every change as a status line in its transcript. The same change from a terminal is orboto live switching, and for scripts the live input set_limit_policy; both are in Switching on and off.

Take over a session

Only one person steers a session at a time, and everyone watching sees who it is. This is the takeover:

• Take over when nobody has. Typing a message takes it over too.
• Give back when you are done. The takeover also ends after 10 minutes without activity and when the session ends.
• Ask to take over when someone else has it. They see who asks and can Hand over with one click, or Keep it.
• Revoke ends someone else's takeover. Only admins with admin:agents:write can revoke.

Answering a question needs no takeover of your own, only that nobody else holds one. While someone else holds it, the answer buttons and the composer say who to ask.

Who may do what

People you share the session with watch it (View) or also answer, type and take over (Operate). Everyone else sees the session as not found. A watcher sees the panel without composer, answers or takeover buttons. Every takeover, request, answer and typed input is written to the audit log with the person who did it.

Watch a session as its terminal

Added in v0.211.0 A session that runs in a terminal - orboto claude, orboto codex, orboto gemini or orboto kimi started in a terminal, a tmux pane streamed with orboto live-session pty, or any command started with orboto live-session terminal -- COMMAND - opens in Admin -> Agents -> Live and in the app under /live as that terminal: the exact screen, colours and cursor, the same picture as on the machine it runs on. The card view is one tab away under Transcript.

What you see

• A small bar above the terminal: the session name, a state dot, how many people are watching right now, and Take over to type or Give back. Read-only means your keys do not reach the session.
• Fullscreen (the button, or Ctrl+Shift+F) gives the terminal the whole screen and hides the bar; Esc leaves it again. While you have taken over, Esc goes to the session instead, so leave with the button (or hold Esc in Chrome).
• Search (the magnifier, or Ctrl+Shift+G) finds text in the scrollback. Selecting text copies it; pasting works where you may type.
• On a phone: pinch to zoom, and while you have taken over a key bar adds Esc, Ctrl (tap it, then the letter), Tab and the arrows. Added in v0.230.0 It also has Enter, so you can confirm a prompt from the terminal view.
• When you open a session late you still see the whole screen and the last 500 lines of its scrollback.

Type into the terminal

Only people who may steer the session can type, and only after Take over to type: the session's own account, its owner, admins with admin:agents:write, or someone it was shared with to steer. Everyone else watches. One person steers at a time and everybody sees who; Give back hands the session back. orboto records every batch of keys you type with its length, never the keys themselves. Fit to my window asks a session without a terminal of its own (one started headless) to take the size of your view; a session mirrored on someone's screen keeps that screen's size. If the program in the terminal stops reading its input, the keys you type are dropped and the session says so.

Privacy and limits

Secrets orboto knows about (the CLI's token, credential-like environment values, codes typed into a login) are replaced with asterisks on the machine before the screen leaves it. orboto looks for them in the text of the terminal, so a secret stays hidden when a program colours part of it, breaks it across two lines or redraws it across the edge of the window. Only the secret's characters turn into asterisks, one per column, so the picture keeps its layout. A secret in a window title or a link is hidden too. A secret that arrives in two pieces is hidden as well: the first piece waits a moment for the rest and leaves as asterisks. A secret is not found when a program prints other characters between its own, for example when it overwrites part of it. When orboto learns a secret only after it was on the screen, every later picture hides it, but what viewers already received stays as it was.

A viewer who is inactive for 30 minutes is disconnected (Reconnect brings the terminal back), and one terminal may send each viewer at most 512 KiB per second. A view that falls behind shows a notice and catches up with a fresh picture. Admins change both under Live session settings on the same page (agent_live_terminal_idle_minutes and agent_live_terminal_viewer_kib_per_second).

To keep orboto claude and the other harnesses out of this, start them with ORBOTO_TERMINAL_CAPTURE=off: they then share your terminal directly and the session shows no terminal.

From the command line

orboto session attach SESSION_ID shows the same terminal in yours, like tmux attach: read-only unless you add --take, and Ctrl-] detaches and gives your terminal back. --transcript attaches to the transcript view instead. When the session's terminal changes its size, your window title shows the new size (and a hint when your window is smaller), and the picture is redrawn at that size.

Share a session

Added in v0.210.1 A live session is yours to share. Without sharing, only the session's agent account, its owner and admins can steer it, and you would have to make a colleague a global agents admin to hand them the wheel. A share gives one person exactly the access you choose, on exactly this session or agent.

Open the session in Admin -> Agents -> Live or in the app at /live and choose Share. Pick a person by name or email and choose a level:

• View: the person watches the transcript and the open questions.
• Operate: the person also answers, types and takes over.

To share every session an agent account starts, lane runners included, use Share on the account's card in Admin -> Agents -> Live. Those sessions inherit the share, and each session's own share list marks it as coming through the account. If your account is an external account, the people search is not available to you: type the person's email address instead.

What the people you share with get:

• The session appears under Shared with me in the Live tab and on the phone route /live, with a badge saying whether they may watch or steer it.
• They receive a notification when you share.
• With Operate they also get the push notification when the agent asks a question.

Revoke takes access back at once: the person leaves the session and loses a takeover they held. Lowering a person from Operate to View ends a takeover they hold in the same way.

Rules for sharing:

• Only the session's agent account, its owner or an admin with admin:agents:write can share.
• You can never share more than you hold yourself.
• People outside your organisation (external accounts) can only watch, even if an operate share was recorded for them.
• If two agent accounts have the same name, sharing by name is refused; use the account id or email instead.
• Every share and revoke is in the audit log as agent.live_granted and agent.live_revoked.

From the terminal:

orboto session grant 0c4f6a10 --user alex@example.org            # view
orboto session grant 0c4f6a10 --user alex@example.org --operate  # view and steer
orboto session grants 0c4f6a10                                   # who has access
orboto session revoke 0c4f6a10 --user alex@example.org
orboto session list --shared                                     # sessions shared with you
orboto claude accounts grant "Review Bot" --user alex@example.org --operate  # every session of an agent account

orboto claude accounts grants|revoke <account> list and remove the account-level shares.

On your phone

Open /live on your orboto address from your phone (for example https://orboto.example.com/live). It shows the same list; tap a session to open its panel full screen. Add orboto to your home screen (on an iPhone: Share -> Add to Home Screen) and it opens like an app. The page works for everyone who may see a session, not only for admins.

Notifications when an agent asks

At the bottom of the list, Notifications when an agent asks turns on push notifications for the device you are holding:

1. Tap Notify me on this device and allow notifications when the browser asks.
2. Tap Send a test to check that the device receives one.

From then on the device shows a notification whenever a session you may steer asks a question, needs a tool approval, hits its usage limit or needs a login - also while orboto is closed. Tapping it opens that session. Only people who may answer get notified; a watcher does not.

The notification carries no content: it says that an agent session is asking, plus the session's name when it runs without a ticket. What the agent asks loads after you tap it and orboto has checked your access. The card lists every device of your account with when it last received a notification; remove a device there, or Turn off on this device. Logging out of orboto on a device turns its notifications off.

On an iPhone, notifications work only after orboto was added to the home screen.

Set up notifications for your instance (admins)

Push notifications need a key pair (a VAPID key) for your instance, which the push services of the browsers use to check that a notification really comes from your orboto. Admins with admin:system:write see Web push for this instance under the session list:

1. Click Generate keys. orboto creates the pair on the server and stores the private key encrypted; it never reaches a browser.
2. Enter a Contact for push services, such as mailto:ops@example.org, and click Save.

The badge changes from Not set up to Ready. Generate new keys later makes every subscribed device subscribe again the next time it opens the session list; devices left on the old key are removed. Until the keys exist, the notification card says that web push is not set up yet.

Sign an agent in from your phone

An agent tool sometimes needs its login renewed, and the machine it runs on has no browser in front of it. orboto turns the login into a question you complete on your own device:

1. Type /login into the composer of a Claude Code or Codex session (or the runner asks on its own when a terminal session prints a login prompt).
2. The card Login needed appears. Tap Open the login page and sign in with the account the agent should use.
3. Claude Code: the page shows a code. Copy it, paste it into Code from the login page and tap Send code. The runner types it into the waiting agent tool.
4. Codex: the card shows a Code to enter there with Copy the code and when it expires (Codex codes last 15 minutes). Enter it on the login page, then tap Done, logged in.

A session shows one login question at a time: a new login prompt replaces the older one, which then refuses a late code. Pi has no login command in the mode runners use; give its lane an API key, or sign it in inside its terminal published through the terminal fallback.

From the terminal

Everything the panel does also works from the orboto CLI, for example over SSH on a machine without a browser:

orboto session list                     # the sessions you may see
orboto session attach 0c4f6a10          # a session with a terminal: its screen, read-only; otherwise the transcript
orboto session attach 0c4f6a10 --transcript   # the transcript view instead, to answer and type
orboto session attach 0c4f6a10 --take   # take over at once, given back when you leave

You read the transcript as it happens, answer questions, approvals, usage limits and logins, and type messages. The takeover works as in the panel, and the same visibility rules apply. The full command set is in the CLI reference.

What stays hidden

A transcript can carry credentials: a token in an environment dump, a password an agent typed into a web page, the login code you just sent. They are masked at every step:

• On the runner, before a line leaves the machine: the CLI's own token, environment values whose name reads like a credential (TOKEN, SECRET, PASSWORD, API_KEY and similar, eight characters or longer), every login code an operator sent (also where a terminal wrapped it across two lines), and every value an agent typed into a web page through the orboto browser tools, which shows as *****.
• On your instance, before a line is stored: the workspace's secret detector runs over every line and stores what it finds as [secret]. Free text you answer with is stored masked as well; a typed input keeps its raw text only until the runner has confirmed it (or it expired, or the session ended).
• In notifications: no content at all, see above.
• In the terminal client: a login code, and the line after a password, passphrase, PIN, one-time code or token prompt, is read with the echo off and shown as ***** on screen and in the local journal. Values shorter than four characters are not masked there.

Settings

All four are changed under Live session settings on the Live page or through the admin configuration API, for example:

orboto patch /admin/config '{"key":"agent_live_takeover_idle_minutes","value":"20"}'

Troubleshooting