One React application, two renderers
The native TUI runs its API and terminal client in the same Node process; each
dashboard does not need a second V8 worker. Standalone devctl daemon remains
available as a separate integration entrypoint. Both renderers share Projects,
container selection, server users, shared subscriptions, approvals, Folders and
MCP Policies. The controller enforces role permissions for both clients.
Numeric shortcuts in Projects follow focus: they select groups when tabs or
group rows are focused, sessions within a multi-session group, and groups in
views with only one session. 0 selects the tenth item. See
navigation and the feature inventory.
apps/tui/src/app.tsx and its screen components are the application. There is
no second implementation of Projects, sessions, grants, budgets or launch forms.
main.tsx renders that application through Ink; web/app.jsx renders it through
React DOM. primitives.tsx is the small layout/text/input contract. The browser
build substitutes web/dom.jsx, mapping it to flexbox, selectable text, links,
buttons and keyboard events. Screen state, validations and API operations remain
in the shared components.
src/actions.tsx provides semantic Action and ActionBar controls with one
callback and availability guard. The native Button primitive retains hotkey
labels and terminal row budgets; the DOM Button primitive uses icons, focusable
buttons, tooltips and accessible shortcuts. Add project belongs to the
Projects screen, with a visible browser/desktop button and Shift+N in focused
TUI content. Both render the existing shared editor without leaving Projects.
Browser toolbars wrap and mosaic
cards grow to fit them. Enter/Space belongs to a focused button, preventing a
second action from the session keyboard dispatcher. Screens keep their existing
keyboard capture and controller authorization; renderers never duplicate API
operations or register extra shortcuts.
TextField, SelectField, CheckboxField and Inline are renderer primitives as well. Native
forms keep their keyboard handlers; DOM forms use labeled inputs/selects and
ordinary browser focus. Inline preserves one bounded Ink text line while the
browser renders controls as siblings, avoiding nested buttons. Browser project
actions call the same application dispatcher as native shortcuts, including its
confirmation and busy guards. Semantic layout regions let CSS fit the browser
viewport without changing the native terminal row budget.
ActionMenu renders the same secondary actions inline in Ink and in a labeled
dropdown in the browser. Project/session toolbars keep primary navigation visible
and group secondary operations in these menus. Native checkboxes retain Space,
Enter and Escape through the screen's keyboard capture; the browser supplies an
18-pixel native checkbox without changing the shared validation or callbacks.
ProjectChangesBrowser owns the shared Project/repository/path/result tree and
its stable selection. Working-tree paths are scoped to a checkout; saved capsules
are scoped to their recorded session. The component resolves refresh/export from
the selected node's repository and does not infer file ownership from an agent.
Mosaic session controls use shared ActionPanel and ActionGroup components.
The browser presents one panel with labeled Agent, Session and Environment
groups, separators and wrapping buttons. Native grouping adds no label rows;
hotkeys and terminal row budgets remain compact. Resource text is separate from
the button labels, and long explanations stay in accessible tooltips.
Browser Mosaic headers use the compact panel variant. Full terminal attachment measures a visible-size stage before constructing its initial PTY request. Layout and window resize observations coalesce subsequent fit/resize messages; hidden or zero-sized terminals never submit fallback dimensions. Bounded Mosaic preview capture only reads the pane and does not resize a running provider.
Session sharing uses the same control-access warning and checkbox in both renderers. The authenticated controller persists its opt-out per devctrl user, including the implicit local operator. See shared sessions.
The shared Handoff action (h) requests context from the source agent through
the controller and waits for the host's saved-file confirmation. Both renderers
show the same progress, failure, retry and account-continuation actions. There is
no user-authored goal/next-step form; preparing context does not restart a session.
Sessions → Settings, Launch Profiles and Context tools also use shared React components. Settings has Project → repository → agent → session navigation, keeping inherited defaults separate from an exact restart target. Launch Profiles provides optional recipe creation, editing, copying, deletion and launch through the existing wizard. Context tools has the same four-tool selection, live operation progress and release notes in both renderers. Browser buttons and native shortcuts call the same validation and controller APIs; role/owner checks stay on the controller. See session configuration and context tools.
The build rejects a web bundle containing Ink, the CLI daemon or the native platform adapter, and verifies that the shared App is included. This is a client rendered application shipped as static HTML/CSS/JS, not a server-rendered terminal screenshot. xterm remains only for actual AI-agent terminals, service logs, provider login and interactive operator CLI operations.
Shared browser surfaces
Projects and Mosaic group tabs share the selected attention categories from Settings → Session attention markers: questions, permission requests, idle agents and exhausted quota. Projects shows a count; groups show only a hand. Hidden sessions are excluded. The per-user preference is shared by the terminal, web and Tauri sources; sound and push retain their own settings. A bounded read-only metadata query applies the current client's hidden IDs without loading session history or exposing private names. See marker settings.
Management screens use proportional UI text and semantic regions instead of reproducing terminal cell dimensions. The same React state and callbacks render Settings cards, account groups, host resource fields, activity calendars, approval requests and inventory details. Ink retains its bounded rows, native selection and keyboard navigation.
DataSection and DataFields provide shared structured metadata. The DOM
renderer uses headings and labelled dl / dt / dd fields; native renders the
same values as aligned terminal rows. Numeric Text.meter metadata supplies real
accessible progress bars in the browser. nativeLabel / DataField.nativeValue
retain terminal bars without parsing ASCII output or duplicating quota logic.
Missing measurements remain unavailable rather than becoming zero.
Activity calendars have individual dated cells and tooltips. Settings cards and approval requests use focusable controls. Browser approval action/constraint checkboxes send the same selected indices as terminal Space toggles; the controller continues to authorize the resulting grant. Dynamic host names, project names, agent output and permission arguments are ordinary data, not layout instructions. Session previews and attached terminals retain monospace text and their original terminal formatting.
Platform boundary
src/platform/native.ts: Node environment, Ink viewport, operator IPC and the existing bounded CLI/API and terminal transport.web/platform.mjs: browser viewport, HTTP API, cached operator status, browser clipboard/link actions and actual agent terminal attachment.src/platform/encoding.ts: shared UTF-8/base64 helpers; no Node polyfills.web/navigation.jsx: URL navigation adapter; native retains its IPC navigation adapter for legacy terminal clients.
Both applications use the same /v1/... controller API and domain models. On the
web, an authenticated gateway forwards requests to that controller using its
operator credential. That credential never reaches the browser. Native transport
and local operator files remain supported. A local TUI can use an existing SSH
forward to a controller; this change does not migrate controller state or rewrite
host enrollment.
Operator-only operations (toolchain upgrade, local checkout/file synchronization,
skills and account transfer) use a bounded, authenticated /ui/... gateway. It
reuses the existing native action worker; it does not start an Ink dashboard.
Only allowlisted state/result files and structured actions are accepted. There is
no arbitrary file API or shell-command endpoint. Interactive setup gets its own
PTY with a fixed argv mapping. Disconnecting that setup terminal terminates its
CLI; disconnecting a managed agent terminal detaches from the agent.
Container detach targets one tmux client through a private per-attachment marker
and verifies its OS user. It never types a tmux prefix into the provider's input,
including while the client is still starting or already has a prefix pending.
The persistent provider PID and other clients remain intact. Native host Control
Room closes its disposable attach helper; its provider stays in a separate
systemd unit. The optional Linux
Docker regression runs with DEVCTL_TEST_DOCKER_TERMINAL=1 pnpm --filter @devctl/runtime exec vitest run src/tmux-client.docker.test.ts and needs no agent account.
Each browser tab now owns its React navigation and forms. Different tabs do not steal dashboard keyboard/size ownership. Controller objects and exchange files remain shared; independent terminals keep existing controller semantics.
The standalone installer also leaves a small local devctrl tui remote SSH
launcher. That optional access mode runs the existing Ink bundle in the server's
controller container and streams its terminal; it does not install a local React
renderer or synchronize laptop files. The regular local TUI remains an API client.
See installation and local-folder requirements.
Remote launch without a local server
Prepare a standalone controller installation, dependencies and built packages on the remote server. A host-agent-only installation is not a controller. From a machine with SSH access:
./devctl web --host my-server --remote-dir /opt/agent-yard
./devctl web status --host my-server --remote-dir /opt/agent-yard
./devctl web stop --host my-server --remote-dir /opt/agent-yard
Start compiles the static web assets on that server, starts its background gateway
and public tunnel, then opens its HTTPS page in the local browser. --no-open
prints the link without opening a browser. SSH carries only the startup command;
there is no SSH reverse/forward tunnel tied to the laptop. Closing the launching
shell or shutting down that laptop does not stop the remote controller/gateway.
The launcher refuses to start web access without a running authenticated
controller. It never installs a new controller or copies local credentials/state.
Running ./devctl web without --host still starts on the current machine. This
is useful when invoked directly on the server and preserves existing local use.
Cloudflare/localhost.run remain optional provider packages. The public address
can change on reconnect; a stable reverse proxy with --url is recommended for
an installed PWA. status supplies the current private link.
Separate static hosting
./devctl web build
# Publish apps/tui/dist/web-static/ on any static HTTPS host.
./devctl web --host my-server --remote-dir /opt/agent-yard \
--client-url https://console.example.com/yard/
The page receives ?api=https%3A%2F%2Fremote-api.example and a private key in
#key=.... The fragment is removed after sign-in; the API endpoint remains in
shareable deep links. The gateway explicitly permits that static site's Origin.
The static site's CSP must permit HTTPS/WSS connections to the configured API;
the gateway's own same-origin deployment requires no cross-origin allowance.
standalone.html embeds the bundle for file-based use. This is optional, not the
remote launch default. Starting the gateway with --client-url file: explicitly
permits the browser's opaque null origin. That permission cannot distinguish
individual local HTML files; only use trusted copies. File mode has no PWA/push.
Authentication and data
Direct clients exchange the private link for an origin-bound revocable browser
session. Requests use a bearer header with credentials omitted, avoiding
third-party-cookie dependence. Same-origin GETs also send the explicit client
origin because browsers omit Origin on those requests. Cross-origin requests
must still pass the actual Origin allowlist. No wildcard credentialed CORS is
used.
Remembered sessions live in this browser's local storage; unremembered sessions use tab session storage. Console endpoint/name metadata is per device. The controller token and provider secrets never enter the bundle. Sign out revokes the server session and attached terminals. Keep the static host trusted: scripts served by it can access its browser credentials. Gateway state stores only session digests plus origin bindings. Legacy cookie clients remain compatible.
WebSocket handshakes and streamed downloads use single-use 30-second tickets, scoped to the requested route and session. Permanent keys/bearers are not put in HTTP or WebSocket query strings. Upload chunks use authenticated requests.
Validation
The shared application includes container selection/navigation, Folders, MCP
Policies and the MCP Approvals repository/request/history browser. Bulk a/d
is handled once by that browser, even when navigation has focus. w withdraws
the selected policy request only; delivery spinners represent the head of each
session queue. These are shared behaviors, not separate browser implementations.
In optional server-user mode the same app switches to authenticated owner-scoped state, account/project/session APIs, terminals and Exchange. Server Users is shown only for a server controller; identities and budgets never live in the client. See server controller and server Exchange. A remote host-agent alone still does not provide a laptop-independent controller.
Build/typecheck, the existing Ink screen suite, DOM primitive/input tests and Node gateway tests cover both adapters. Direct-auth tests cover CORS rejection, origin binding, restart persistence, logout and ticket reuse. Browser verification uses an isolated controller fixture, validates DOM navigation and mobile widths, and refuses to start a dashboard PTY.
Local and invitation-based server access use the same controller user identity and shared session wizard. Local mode chooses one implicit operator, without an extra sign-in step. Administrators manage shared Claude/Codex account grants in the same Server Users panel for both renderers. A shared subscription is marked in Accounts and session selection; its quota is common while histories/storage remain private. Shared account workflow (source access required).
Current navigation and status controls
Digits 1–9 and 0 select the first ten visible sidebar sections in their displayed order only while navigation has focus; Enter moves focus into the selected content. In Projects content, digits keep the existing group/session selection behavior: groups when the group tabs have focus or a group has at most one visible session, otherwise sessions within the selected group. Meta/Ctrl combinations and active text inputs do not trigger sidebar selection. MCP Approvals displays its pending count and a local spinner while rules are being delivered; completed, withdrawn or failed deliveries stop the spinner.
Accounts shares separate five-hour and weekly elapsed-time bars with remaining-percentage labels with the browser renderer. They tick locally, use official resets and verified window durations, and keep quota consumption separate. Unknown duration/reset is explicitly unavailable. Shift+C in Dashboard, Templates and Projects opens the common CLI release-notes panel. Integrations → Remote interface → Telegram uses the same setup component in both renderers; bot credentials stay in the controller keyring.
Dashboard → Resources (d) uses the shared resource-history screen in Ink, browser and desktop. It loads history independently of console state, switches between host/container scopes and time periods, and opens individual timelines. The controller collects samples even when every client is closed. See resource history for retention, counters and ownership.
Projects tree and Mosaic render the same timestamped SessionWorkStatusRow in
Ink, web and desktop, reserving its actual line in native tile height accounting.
Settings → Session status uses a shared checkbox and editable minute interval;
the per-user policy runs on the server. First-use Control Room opens the shared
host/account form and saves it before launching, rather than sending an incomplete
start request. See progress snapshots and
Control Room.
Its shared ControlRoomChat owns the same draft, paged native messages and input
submission in Ink, web and desktop. Ink uses the measured content width and
keyboard history navigation; DOM uses message cards, a scrollable conversation
and a multiline composer. New replies follow the bottom only while the reader
remains near it. Voice input returns reviewed text to the existing draft,
with no automatic send. Microphone capture is a client adapter; subscription
selection, authorization and execution stay on the server.
Dashboard uses the same project activity cards in both renderers, with daily heatmap cells, native token/Git totals and exact/relative last activity. a opens Project activity (the default tab); e opens Attention with its pending count. Cached summaries load independently from the main inventory. Native cards page within the terminal; browser cards use the scrollable grid. Partial coverage stays explicit; empty cells consistently show no recorded activity. Tokens use k/m suffixes. Last and sort order follow tokens/commits. h hides/restores selected cards, v opens Hidden, and Enter opens an organization’s repositories. Visibility persists per controller user across all renderers. Tab changes focus without replacing the activity view; the legend/actions stay at the bottom.
Integration navigation
The sidebar contains one Integrations entry. Its Decisions group opens Decisions API; Remote interface opens Telegram, Slack or Microsoft Teams. Arrow/Enter navigation and click actions use the same React component in both renderers. Esc returns from a connection to the grouped list; a child credential/model form retains its own keyboard capture until closed. Old advisor deep links resolve to Integrations?item=decisions. Optional messenger packages expose setup field metadata; hidden credentials stay in the controller keyring. Provider behavior and API.
Decisions API has a visible Settings button in every view (w in TUI). The five checkboxes select which tasks the API may evaluate and save immediately. Dashboard CLI update ranges open the selected tool's release notes directly in the web renderer. TUI provides Shift+C, followed by t to switch tools. Long attention badges include an explicit separator before their counts.
Approval delivery status is polled independently of the selected section; leaving Approvals or opening another form does not freeze the sidebar indicator.
Compact management surfaces
The console frame, sidebar and section header remain mounted while opening session names, subagent details, sharing, cleanup, context tools and release notes. Only the content pane changes. Switching sections dismisses that pane's editor; back/cancel returns to its parent without restarting sessions.
Browser and Tauri use a responsive account mosaic, with account identity, five-hour and weekly consumption, time-remaining bars, model preferences and actions in each card. Native Accounts keeps a single vertical list in both compact and detailed views. Unavailable quota stays unavailable and exhaustion remains red. Hosts displays all hosts as resource cards in the browser, while Ink keeps its selected-host view. Each card uses the existing fresh/stale metrics and shared inspect/deploy callbacks.
Browser Control Room opens the existing paged conversation directly. Its compact header groups model, execution and integration controls; speech options live in a disclosure. No new conversation transport or model request path is introduced. Launch Profiles uses ordinary labeled text/select fields in the browser and the same profile validation and persistence as native keyboard editing. Templates shows every package in a scrollable list rather than a truncated terminal slice. Dashboard grid rows size to card content so heatmaps and footers cannot overlap. Focused Project session cards have a bright outer ring and selected header; quota/error frames keep their separate inner boundary.
Web Access is removed from primary navigation. Native TUI and desktop expose it under Settings; browser clients omit it. Public URL provider configuration remains in Integrations, and the command-line web launcher is unchanged.
Layout regression QA: build apps/tui/web/build.mjs, then run
apps/tui/web/management-layout.browser.integration.mjs with the optional
DEVCTL_PLAYWRIGHT_MODULE, DEVCTL_BROWSER_EXECUTABLE and
DEVCTL_BROWSER_SCREENSHOTS overrides. The isolated fixture checks desktop/mobile
management screens, a 48-package scroll list, multiple hosts, account session
expansion, profile fields and a retained console shell. No provider credentials
or live agent terminals are used.
Exchange keeps its current listing and upload receipt when the controller refreshes the parent screen. A changed callback no longer remounts its request lifecycle; subsequent operations use the latest transport. Settings keeps a bounded native list with selection-following pagination. Old Web Access links resolve to Settings.
Account consumption meters use a shared green → amber → red scale in native and browser renderers. Empty cells remain muted; elapsed quota-window time keeps its separate cyan bar. The scale changes presentation only: reported percentages, window resets and explicit exhausted-state labels retain their existing meaning.
MCP navigation
The sidebar groups MCP Servers, Policies and Credentials under MCP. Switch
between its tabs with a click or Ctrl+Left / Ctrl+Right. Existing section links
redirect to the corresponding tab. Approvals remains a separate sidebar entry
with its pending count and delivery indicator.