Control Room

Control Room provides independent Claude or Codex chats for operating a devctrl server. Open Control Room in TUI, web or the desktop app to enter the selected chat immediately. Each chat has its own native session and conversation history. The canonical server operator has server-wide administration. A tenant administrator can use an isolated Docker manager to send input and read output for their own private sessions; its general controller operations remain limited to reading the controller version. Ordinary server users cannot create or access Control Room. Host execution and management of neighboring containers require the canonical server operator.

On first use, the chat offers Configure Control Room, which opens Settings → Control Room. Choose Execution, agent and model settings to select the initial host and account. A single eligible account or online host is preselected; multiple choices require your selection. Save and start saves those defaults before creating the session on that host. Cancel leaves all existing sessions untouched. The overview shows the selected host and account.

Open Settings → Control Room → Execution, agent and model settings, select an existing account, online execution host and execution mode, then start the managing session. Claude and Codex have separate default-model fields. Leaving a model empty uses that CLI's inherited default. Changes apply to the next managing session and never restart a working provider process.

Model fields use the server's model catalog. In TUI, press Enter on a model field, choose with ↑/↓, and press Enter to confirm; Esc keeps the existing value. ←/→ also cycles models directly. Web and desktop provide the same choices as dropdowns. Agent default (CLI) clears the override, and saved model IDs remain selectable even when absent from the catalog. Catalog entries do not guarantee availability for a particular account. The focused save button is highlighted.

Execution and persistence

The managing session uses the existing durable session launch, PTY, managed accounts, lifecycle hooks and terminal attachment. Execution mode selects one of two environments:

Mode Where the CLI runs Authority
Docker (default) Its own persistent, repository-free container; no nested Docker The checked operator API manages infrastructure, sessions and neighboring containers. No raw Docker socket is mounted.
Host Directly on the selected server as the OS user running server tooling The process inherits that OS user's filesystem and operating-system access, in addition to operator MCP.

Choose a mode with the shared dropdown in web/desktop. In TUI, press Enter on Execution mode, select Docker or Host with ↑/↓, then Enter; Esc preserves the previous value. ←/→ also cycles available modes. A mode unavailable on the selected host cannot be selected or saved.

The overview reports the session's actual execution mode and, when observed, its Host OS username and UID. These describe the running process rather than the next-launch preference. Changing mode saves a default for the next new managing session; it never relocates, stops or restarts the current process. A mismatch is shown explicitly until a new managing session is started.

Host mode has the tooling user's OS privileges. Revoking Control Room MCP authority prevents future MCP management calls, but does not remove OS access from an already-running Host process. Stop that process to end its OS access. Ordinary project containers and sessions keep their existing isolation.

Host execution requires a verified Linux host transport. Fresh limited-user installations use a private Unix socket and a same-user systemd service; neither the socket nor its directory is mounted into Project containers. Existing rootful Linux installations can use a short-lived namespace helper. That helper checks the server's mount namespace and tooling UID/GID. The persistent tmux and CLI belong to a native host systemd unit, so removing the helper or disconnecting a terminal does not end the session. Docker Desktop's Linux VM is not advertised as the physical Mac/Windows host. An unsupported host cannot silently fall back to a container.

Before a new Host launch, devctrl resolves the official CLI release and prepares a private, immutable version directory under the execution data root. It does not replace a globally installed CLI or the binary used by a running session. Only the selected account's authorization JSON is exported by the trusted host agent into its private Host runtime. Provider history and unrelated account settings are not copied. Refresh synchronization preserves the canonical account UID, checks the destination revision before publishing, and preserves both copies if they changed concurrently. A stopped launch can use a renewed canonical account without restarting other sessions.

Claude runs with its normal permission prompts in Host mode, including when the current tooling user is root; devctrl does not pass root-forbidden permission-bypass flags. Native host dictation has no verified microphone bridge: select an available Claude source in a Docker workspace, or explicitly configure external transcription. Container resource values remain unavailable for a containerless Host workspace; the ordinary host metrics include its work. Container-specific automation, including automatic compaction and periodic side status prompts, currently remains a Docker capability. Host sessions expose their native lifecycle/model hooks and conversation, but do not report those container-only automation jobs as applied.

Its internal Project and session are explicitly classified as control-room; they are excluded from ordinary Projects and Dashboard activity. The separate menu retains its status and statistics.

The execution host is explicitly pinned to the operator's selection; the scheduler cannot substitute another host or Local Docker for a Control Room launch. Controller reloads preserve this repository-free classification and remove Git metadata synthesized by older migrations. Accepted lifecycle commands are handled before retained-session scans and inventory collection on the execution host.

Settings, server authority, session/workspace identity and operation counters are stored in the controller database. Accepted host launch commands continue if the client disconnects. Provider conversation files use the same durable account/session storage as other managed sessions. No agent launches until the operator selects an account and requests Start.

The Control Room screen shows recorded operator calls, failed calls, submitted prompts, last operation time, running managed-session count, the managing session's observed model, native token observation and container CPU/RAM where reported. Native token observations retain their scope, such as the latest response or whole thread; they are not subscription billing totals. Unavailable measurements remain unavailable.

Native Remote Control

Ordinary Claude Control Room launches enable Claude's native Remote Control in both Docker and Host mode, including resume of the same native conversation. Future launches retain only the official Claude link from raw terminal output, including OSC 8 footer links on older tmux versions. This bounded collector discards all terminal text and exits after its first link or 60 seconds. The chat reads its small private artifact with account, conversation, process generation and file-owner checks. No pane history is read to infer a link, and no terminal attachment is required. An existing pane output pipe is preserved; devctrl does not replace a capture or log pipe to obtain a link. Open native Remote Control and Copy Remote Control link are available in TUI, web and desktop. TUI also provides Ctrl+O and Ctrl+Y. Opening or copying the link preserves the draft and does not send a prompt. The link is stored with its process generation and is discarded when that generation or conversation changes. Provider account and organization eligibility still determine actual link availability; requesting Remote Control does not establish that a connection succeeded.

A working process created before this launch behavior is preserved. Its link is shown if already available; otherwise native Remote Control becomes enabled on its next launch or resume. devctrl does not interrupt or restart it to activate Remote Control. Restricted review and diagnostic workers keep Remote Control off.

Codex provides an experimental native remote-control daemon with short-lived pairing, rather than a per-session launch option. devctrl does not yet start or pair that daemon for a Control Room chat: account, conversation and process isolation must be verified first. Use the existing authenticated devctrl chat or terminal for those Codex sessions. This does not create public control links. The official Codex command reference describes that separate native lifecycle. The Claude Remote Control documentation describes the interactive launch flag and provider eligibility.

Conversation

Open chat is the primary action. It shows the managing session's actual user messages and Claude/Codex replies, with timestamps and model metadata when the native transcript records it. Replies come from the same managing conversation, not a second model call or a terminal screenshot. Open terminal remains available for CLI-native choices, permissions and diagnostics.

Type a message and choose Send message. While the CLI is working, Send follow-up adds context using that CLI's steering or queue behavior; it does not restart or interrupt the session. A submitted message is marked as awaiting native confirmation until its delivery ID is matched to a native message ID. The canonical record replaces that pending row; deliberately repeating a prompt still creates a separate message. Sending clears the composer immediately and keeps the submitted text in history. You can prepare the next draft while native confirmation is pending; a delayed acknowledgement or delivery failure leaves that new draft intact. An uncertain message remains visible once. Check last delivery / R checks its original delivery UUID without creating another message. Submission alone is not reported as task completion.

Known Claude whole-message paste envelopes are displayed as their actual text and matched to the native input receipt. Literal XML in examples, assistant replies and unrelated markers stays intact. This does not read paths from a message or dereference pasted-file references. Native messages and unconfirmed inputs use their authoritative timestamps; equal or missing timestamps retain the native order. A later confirmed native ready/waiting/completed event stops response progress even if delivery acknowledgement remains uncertain.

The conversation refreshes every two seconds while open. Reads are bounded to 40 messages per page, with at most 160 messages retained by the current client. Earlier messages reads an opaque cursor instead of downloading the full history. Browsing older messages keeps small activity/receipt checks running without replacing the history you are reading; Latest messages returns to live replies. The native conversation files remain the durable history when you close the client. A changed provider conversation or process generation resets the displayed history instead of mixing sessions.

Only visible parent user/assistant text is returned. Tool calls, raw tool results, reasoning, system/bootstrap instructions and subagent conversations are excluded. The administrator's current managing-session registration and ownership are checked before and after a host read; neither a session ID nor a history cursor can select another user's conversation. Known credential patterns, operator credentials and terminal controls are removed before rendering. History requests do not attach a terminal, restart the provider or send a prompt.

A new conversation can have no transcript until its first message. The reader supports the current native JSONL files. Compressed-only Claude archives are shown as an unsupported history format, with Open terminal available; they are not presented as an empty successful import. Long messages are explicitly truncated in this view. Older history remains in the native provider files.

Input receipts retain the last 20 delivery IDs per owner. A retry with the same ID returns its previous status rather than sending Enter again; a changed message cannot reuse that ID. Accepted and uncertain submissions are distinct from a native user message or an assistant's completed reply. The provider's current lifecycle may be unknown or stale; the chat preserves that uncertainty. Progress appears inline with conversation history, separating submission, acceptance and native work, with thinking or tool activity only when native hooks report it. It shows the last activity age, host/process health and last successful check. A missing progress update is not reported as a dead process. Refresh conversation checks the existing message and session without resending a prompt. History reads have a bounded timeout.

In TUI, Enter sends, Tab switches between the composer and history, and PgUp/PgDn scroll history. While history has focus, o loads earlier messages, l returns to the latest page, v opens voice and t opens the terminal. Esc returns to the Control Room overview. Unsent text is preserved when you leave the conversation or add a reviewed voice transcript. Interrupt response sends a single native interrupt to the current running response, without closing the chat, restarting its process or discarding your draft. Back / Esc only leaves the chat. Ctrl+X activates Interrupt in the native TUI or when browser focus is on chat controls; native clipboard shortcuts inside the browser text editor retain their normal behavior. The controller rechecks the exact conversation/generation and current native working state; busy compaction, questions, stale state and inactive sessions cannot be interrupted through this action. Interrupt sent confirms delivery, not task completion. TUI, browser and desktop keep history in its own bounded viewport with the composer and actions below it. Browser wheel scrolling and PgUp/PgDn affect that history rather than moving the entire console. Their multiline composer uses Enter to send and Shift+Enter for a newline. Reviewing a voice transcript appends it to the existing draft without removing typed context or sending the message.

Requests that need human attention

The left navigation shows a count beside Control Room only when a current request needs a human action. Open Control Room, then Needs attention near the heading to see the bounded list. Opening the list sends no native input and preserves the current chat draft. An item opens its exact existing approval or chat; manager recovery also offers the current Control Room settings.

The count includes fulfillment review, explicitly awaiting dispatch, manager configuration/model/account recovery, current Control Room permission requests, and fresh provider questions or native permission choices. Automatic busy waits, running or queued tasks, normal idle prompts, verification, completed/failed history, cancellation, expiration and revoked registrations do not add to it. Repeated projections of one request and a native permission prompt already represented by its pending approval count once. Distinct approval decisions remain distinct. Project session attention has its own separate counter.

Only the canonical operator sees requests requiring its cross-user fulfillment review. Other administrators see their own registered Control Room chats and owned approvals. Counts come from the existing bounded attention feed, even when sound is off; initial state does not contain request histories. The current list is available at GET /v1/control-room/attention?limit=25&cursor=… with at most 50 rows. Existing decision, chat and settings authorization remains in force.

Operator MCP

Administrative role

The managing session acts as devctrl's administrative agent. A request means investigate, perform the supported operation and verify the observed result; routine decisions do not require another confirmation. It uses its existing operator operations rather than asking the user to contact an operator, paste permission text or delegate the same administration to a coding session. An access repair covers the relevant grant, document, gateway, network, file delivery and endpoint checks, not just a policy-text update.

Ordinary Project approval instructions govern the managed coding workloads. They do not require the canonical operator's Control Room to approve itself. The prompt does not expand API or OS privileges: tenant administrators keep their narrower operations, credentials remain private, and disruptive changes outside the user's request still need the user's intent. Genuine missing information or external authentication is reported with the exact blocker.

Current inventory and bounded reads

The managing session starts with a small, controller-authored inventory: visible Projects, repositories, hosts, workspaces, sessions, account aliases, services, resource grants and document IDs. A revision hashes structural metadata. CPU/RAM samples, heartbeat timestamps, prompts, environment values, credentials and host filesystem paths are excluded.

The controller checks for changes every five seconds and coalesces pending writes to ~/DEVCTRL.INVENTORY.md. The Linux host-agent atomically replaces this private file after rechecking the current owner, native conversation and process generation. Background refresh works while TUI/web are closed and does not send a prompt, press Enter, interrupt native work or restart a session. Hosts advertise control-room-inventory-v1; older hosts retain the bounded startup index and API access until upgraded.

Claude receives a short official UserPromptSubmit additional-context hint once per changed revision, attached to a real user turn. The existing devctrl-owned hook file can be refreshed in place without editing unrelated native hooks. Explicit Control Room chat input also carries a revision/file hint when needed; chat displays the original user text. A generic native Codex pre-turn hook is not invented: Codex uses the explicit chat hint and the current inventory file/API.

Use these operations instead of copying an entire catalog into a prompt:

Document metadata/content and edits recheck ownership. Another tenant's global binding does not publish a private document; only an authorized shared binding does. These APIs do not expand a tenant administrator's Control Room tool role: its generic operator tool remains limited to the existing version operation. The signed-in administrator may read its own inventory through the console API.

An oversized operator result returns a bounded error with paging suggestions. The MCP process stays connected and can serve the next request. The complete duplicated text/structured tool envelope is kept below the native bridge limit.

Chat delivery and interruption

Submitted chat messages retain their delivery UUID and the exact native message ID after confirmation. Correlation is fenced to the native conversation and generation and excludes native messages present before submission. Confirmed receipts remain available after a message leaves the latest history page. Deliberately repeated messages keep separate IDs. Native lifecycle source, observation time and staleness are reported separately from history-read time.

POST /v1/control-room/interrupt takes deliveryId, sessionId, providerSessionId and generation. It sends one native Ctrl+C through the existing terminal input path; it never sends a prompt/Enter or stops/restarts a process. Only a verified, fresh working native turn can be interrupted. Idle, starting, compacting, question and stale states are rejected. A repeated delivery ID cannot repeat Ctrl+C, including uncertain transport delivery. sent means the interrupt byte was submitted; native lifecycle determines when the turn stops. Back/Esc only leaves the chat and does not interrupt it.

Only the exact registered, enabled managing session receives these tools:

The matching private HTTP operation is GET /v1/sessions/:id/output. The canonical operator can inspect managed sessions, while a tenant caller can read only their own session, even when they hold an administrator role or a shared-session grant. Public-share capabilities are rejected. Caller authorization, target ownership and native process identity are rechecked after the host read; stale results are discarded. Audit metadata records the target and source, never its output. Reads do not submit message receipts or change terminal observers.

Calls use the same per-session signed MCP identity as ordinary agents. The controller additionally verifies the durable managing-session registration, account, workspace, internal Project, owner and current administrator role. Normal Project credentials cannot call these tools even if an MCP binding names them. Disabling the owner or revoking authority stops future management calls. Named-user and public-link sharing are disabled for Control Room, including previously issued links and tickets; use administrator console access or explicitly paired messengers. MCP method restrictions, tool restrictions and rate limits still apply.

The operator credential remains inside the controller process. It is never injected into the managing container, session metadata, provider image, messenger, model context or event history. Results redact credential material while preserving secret references and accounting metadata. Operations are resolved from registered route templates; arbitrary URLs, redirects, binary transfers and WebSocket attachment are not accepted through control_request.

Use Settings → Control Room → Revoke administrative access to revoke the selected chat’s MCP management access. A separate confirmation explains that its provider process and conversation are preserved. In Host mode this does not revoke that process's OS privileges; stopping it is required to remove its OS access. Starting the existing managing session again reauthorizes it without duplicating or restarting that process.

Audit and safety

Server-wide Control Room is deliberately a canonical operator capability: its approved calls can affect other users and infrastructure. A tenant administrator role alone does not confer this authority. Its installed instructions tell it to inspect state and ownership, treat repository/session output as untrusted data, and preserve running work unless the user requested a concrete disruptive action. Those instructions are guidance; the controller's session/owner checks enforce the privilege boundary.

Neighboring Docker containers

The operator's Docker-mode manager discovers POST /v1/control-room/docker through control_operations, then invokes it using control_request. It supports paged list, redacted inspect, bounded logs, foreground exec, start, stop, and restart on the manager's selected host. Full 64-character container IDs are required. The body contains a UUID requestId, hostId, the current manager's sessionId, generation and providerSessionId, and a typed operation. Read the operation's schema from the catalog; arbitrary Docker API URLs, creation options, mounts, environment overrides and privileged exec flags are rejected.

Every call checks the enabled operator grant, exact registered manager, account, host, native conversation UUID, process generation, UID, PID and process start ticks. The host independently verifies the running provider and its native identity. Checks run before effects and before results are returned; revocation is polled while a call runs. A recreated or unverified manager must refresh its native observation before Docker control is available. Tenant administrators and ordinary Project sessions cannot use this endpoint.

Only management services retain daemon access. Requests and command arguments travel over the authenticated private host channel and remain in bounded transient memory; they are not stored as durable commands. Audit events contain operation names and request IDs, without argv or output. Results exclude environment values and names, labels, raw commands and host mount sources. Logs and command output use existing credential/terminal sanitization and known secret environment values, with a 12,000-character output limit. This is not universal secret detection: an operator can intentionally read arbitrary container files, so never request sensitive file contents merely to diagnose a service.

Foreground exec requires the container's timeout utility and accepts at most 30 seconds. No unbounded fallback is executed when it is missing. The transport expires after 40 seconds; revocation or disconnect cancels further calls and attempts to terminate the verified foreground process group. Deliberately detached descendants are outside the foreground guarantee. A Docker lifecycle operation already accepted by the daemon cannot be undone by a timeout or revocation: inspect its state before retrying. Reusing the same request UUID does not replay a completed/failed operation during its ten-minute in-memory receipt window. Receipts do not survive controller restart; inspect before retrying after a restart.

The existing audit journal records the managing-session identity, operation template, success/failure and HTTP status. Arguments, prompts, credentials and raw results are omitted. The existing access-attempt history also records MCP admission and policy/rate-limit failures. Audit JSONL export and configured external log collectors include these events.

An operation timeout can follow accepted work. Inspect the job or resulting state before retrying; do not assume that disconnecting cancelled it. The response limit is 2 MiB; use paginated operations or the native file/stream interface for large histories and artifacts.

Voice

Open Control Room to use Open terminal or Voice input from the composer controls. These actions stay with the conversation in TUI, web and the desktop app. Execution and voice settings live in Settings → Control Room; Telegram, Slack and Teams setup lives in Integrations → Remote interface. In TUI, press ↓ from the message draft to focus these controls, then use ←/→ and Enter to choose an action. Typing t or v in the composer remains ordinary text. Choose Voice input to record inside the chat. Subscription mode uses an available Claude account without a separate transcription API key. Review and edit the transcript, choose Use transcript to append it to your existing chat draft, then send the message separately. This integration cannot use a Codex subscription for dictation; a Codex managing session can still use an eligible Claude account for voice. External transcription remains an explicitly selected advanced fallback and is never used automatically. Browser and desktop clients use the local microphone; Docker and remote TUI use the authenticated local microphone bridge when launched through devctl. See Voice input for availability, recorder requirements, limits and cleanup.

The chat header reports an exhausted conversation account and offers an explicit new-chat account choice, preserving the original history and current draft. Model quota and dictation availability are independent. Enhanced native voice diagnostics and spoken-language selection require the updated host helper; a controller or browser update alone cannot change an older helper's behavior.

Read replies aloud

The conversation offers Listen latest reply, a Listen to reply action on each browser/desktop assistant message, and Stop speech. In TUI, focus history with Tab, use [ / ] to select a reply and s to read it; x stops playback. The selected assistant heading is marked s listen. These actions only play the visible, redacted assistant text. They never send a prompt, press Enter, change a draft, or read tool output, reasoning or user messages.

Read new completed replies is off by default. Enable the checkbox, or press A with TUI history focused. The device remembers the setting. Opening a conversation or enabling the setting establishes a baseline: saved history is not read aloud. Automatic playback waits for a confirmed ready-for-input state and an identical reply on a second conversation refresh. Unknown, disconnected, working and permission-waiting states do not start automatic speech. Native message IDs prevent duplicate playback; at most three new replies are queued. Manually reading a reply also excludes it from subsequent automatic playback.

Speech uses the client device's installed voice, without a paid speech API:

Interface Local output
Browser Web Speech synthesis voices explicitly reported as localService: true; remote/cloud voices are excluded
Desktop app Bundled native helper using the system engine; local WebView voices remain a fallback if the helper is unavailable
Local TUI macOS say, Windows System.Speech through PowerShell, or an already-installed Linux espeak-ng/espeak
Docker-rendered or SSH TUI The same local engines through the owning local launcher and its private IPC/authenticated loopback SSH bridge

The desktop native helper needs Python 3.9+, as used by desktop SSH setup. Linux needs an installed speech engine and working local audio output. Missing engines show a setup explanation; devctrl does not install a package or substitute an external voice service. A remote TUI without a local bridge cannot use the server's audio device. Reconnect through devctrl tui remote or use web/desktop.

Playback is bounded to the first 6,000 characters per reply and three minutes. Long manual replies show the character limit. Starting another reply cancels the previous one; leaving the conversation or disconnecting the launcher cancels playback and clears its queue. Text is passed through stdin or private runtime IPC, never shell commands, process arguments or logs; temporary payloads and results are removed. The native preference file contains only autoRead, not conversation text. Browser preferences stay in that client's local storage.

Speech is a client presentation feature. It has no server speech endpoint or MCP operation: an agent cannot make your speakers play through its server MCP authority, and enabling speech does not change session or account permissions.

Telegram, Slack and Teams

Pair the installed messenger integration with your administrator console user using the existing one-time pairing flow in Integrations → Remote interface. The same setup screen includes Control Room destination for authorized administrators. Select a specific running chat, or Regular session controls to leave Control Room routing disabled. Switching chats in the console never changes this destination. The integration then exposes a separate Control Room action and accepts ordinary messages as prompts to that registered managing session. /control (or control in Slack/Teams) shows its output. Explicitly choosing Reply for another session continues to target that selected session.

Routing is checked on every message. It requires the same enabled administrator, configured messenger and exact active managing-session registration. It grants no authority to other paired users. Existing approval notifications, session attention notifications and user-bound callbacks retain their existing behavior. Revoking Control Room authority removes its default messenger route; it does not disconnect the bot or restart any session.

HTTP operations

The existing operator MCP controller_operations / controller_request can discover and manage these routes:

Method Route Purpose
GET /v1/control-room Settings, managing session/workspace and bounded statistics
GET /v1/control-room/chat?limit=40&before=… Bounded native conversation history, delivery confirmations and current lifecycle
PUT /v1/control-room/settings Execution mode (docker or host), agent, account, host, per-agent default models and selected messenger routes
POST /v1/control-room/start Start or reauthorize the managing session
POST /v1/control-room/revoke Revoke server authority while preserving its process
POST /v1/control-room/input Submit a reviewed prompt with a unique delivery ID

The voice routes and encrypted credential handling are documented separately. No paid model or transcription API is required by ordinary automated tests. Tests exercise the actual controller routes and mock only external providers/recorders; paid live agent execution and real microphone capture require explicit integration setup.

Reply formatting

The shared chat renders assistant Markdown: paragraphs and line breaks, headings, lists, emphasis, links and fenced code. Browser and desktop preserve whitespace inside code. Native TUI keeps a bounded, scrollable text history with the same paragraph/list structure. User messages retain their literal formatting. Model HTML is displayed as text; images are not fetched, and only HTTP(S) links are actionable. Formatting never changes the saved native conversation or submits a prompt.

Independent chats

Use Chats above the conversation to select, create or rename a chat. In TUI, focus history with Tab and press c; use ↑/↓ and Enter in the chat list, n to create and r to rename. Each chat has its own provider session, native history, input receipts and unsent client draft. Switching chats does not stop the other agents. Existing installations retain their original session as Main.

Execution, account and model defaults in Settings → Control Room apply when starting a new managing session. Existing sessions retain their current process, account, execution mode and conversation. Administrative access is registered and revoked separately for each chat. Messenger destinations are explicitly pinned to one chat, independently of the console selection.

See Control Room chats for migration, authorization and the pinned HTTP API. The legacy Control Room routes operate on the selected chat; clients should pin history, input and interruption to a chat ID when switching.