Fleet Console

Standalone loopback web console for observing live output streams and Console-owned Agent and terminal sessions.

What It Does

Fleet Console core owns HTTP, Agent execution, Chat, global Shell, PTYs, tickets, WebSocket transport, and AI Gateway composition. Plugins consume explicit Console capabilities; they do not depend on a Terminal plugin.

• Console-owned terminal sessions and observed jobs in a navigable rail.
• Workspace hub sessions created through an in-console directory browser — no OS-native dialog.
• Console-spawned Agent CLI PTYs with in-process observation.
• Codex/Fleet Wiki browsing under the shared Console GNB at /console/codex.
• Codex Cowork lets you open a Wiki entry in a focused AI editing session: compare its immutable current version with a live draft, give the assistant selected text or annotations as context, and Apply once when ready. Your draft and conversation survive refresh or restart, while knowledge remains unchanged until that final Apply; Cowork has no terminal or PTY access and keeps provider details, workspace paths, and credentials out of the browser.
• Browser observer snapshots and SSE streams backed by console-owned global observed ids.
• Browser terminal access through short-lived tickets over WebSocket.

Agent is a durable Console-owned Operation (pluginId: null, type: "agent"). Shell is one global non-durable surface with a Console-owned lifetime. Terminal and Chat are Agent execution adapters, not plugins.

Runtime Channels

| Channel | Purpose | Token Boundary | |---|---|---| | /observer/* | Browser snapshot and SSE observer surface. | Loopback-only; no browser bearer token. | | POST /api/v1/theaters/folder-listings | Returns a directory listing ({ path, parentPath, roots, entries, truncated? }) for the given path, or the server home directory when path is null. Directories only, non-recursive, capped at 500 entries. | Requires the terminal Origin boundary (isTerminalAuthorized); no adminToken. | | POST /api/v1/theaters/folder-grants | Validates the client-supplied absolute path through validateAbsoluteDirectory and returns a one-use { folderGrantId }. | Requires the terminal Origin boundary; no adminToken. | | /api/v1/shell/* | Shell launch and ticket routes for the global Shell. | Shell cwd is resolved server-side from the selected Theater; browser receives only one-use terminal tickets. | | /api/v1/agent/* | Agent launch, session, ticket, job, event, tenant, and state routes for Agent Operations. | Requires the terminal Origin boundary; MCP/session tokens remain server-only. | | /api/v1/terminal/ws | Console PTY and Chat WebSocket transport. | Short-lived one-use ticket and Origin authorization. | | /console/ | Static React client served from this package's dist/client. | Served directly from the loopback console URL. | | /console/codex/* | Console-owned Codex/Fleet Wiki web, workspace API, and migrated Maritime Codex client. | Admin workspace registration uses the lock bearer token; browser reads stay token-free on allowed local origins. |

/observer/tenants may include terminalSessionId for plugin-owned terminal sessions. Shell and Agent routes live under /api/v1/{shell,agent}/*; WebSocket transport lives at /api/v1/terminal/ws.

Session Binding

When Console creates a terminal session, it generates a session id and resolves every Agent CLI, including AI Gateway operations, through the shared fleet-admiral runtime. It keeps the selected absolute cwd server-side and records non-secret session metadata for observer hydration through generic console operation and event capabilities.

Folder selection is handled entirely in the browser UI: the React directory browser modal calls the console-owned POST /theaters/folders/list route to browse the server's local filesystem, then calls POST /theaters/folders/grants once the operator confirms a directory. The resulting one-use grant is consumed by Theater registration; Shell and Agent launches resolve cwd from the Theater server-side. No OS-native dialog or child process is involved. The browser modal works in remote and headless browser sessions without any OS-level dialog support.

Folder grants are one-use and in-memory. Browser-side cancellation stays local to the modal and does not call the server grant endpoint.

Computer Use observation output

computer_apps({ query, includeWindowState: true }) inspects window state without activation or capture for up to 20 matched installations. It reports truncation; use an exact app path to narrow the read. no_window means a successful AXWindows read returned an empty list; unknown preserves permission and lookup failures. A running process alone is not evidence of an open window.

computer_open({ app, reason, activate: false }) explicitly launches/reopens one absolute .app installation through the macOS background open request (open -g). activate defaults to false; an app can still activate itself, so focus preservation is not guaranteed or restored. Use activate: true only for authorized foreground opening. Background readiness means a non-minimized AX window exists; it does not promise visibility or background capture. A later computer_state with allowActivation: true may take focus. Use it only when opening that app is within the user's task. It requires no snapshot, invalidates prior snapshots, and shares the local-control, opt-in, cancellation and session ownership gates. It does not capture, type, switch installations, force-quit, or retry. requestDispatched means the request process started, not that a window opened. Check windowReady, then request computer_state for a new observation. Apps can ignore reopen or show a chooser; an unready result requires user guidance rather than replaying input. Closing a window differs from minimizing it: even with allowActivation: true, a confirmed empty window list refuses capture/input with computer_use_no_action_window. Unknown window state is not guessed to be empty. A confirmed hidden app refuses capture/input with computer_use_app_hidden: native AX reads can succeed while the separate Desktop live preview is blank. When showing the app is authorized, request background reopen, verify hidden: false, and read fresh state. Window readiness requires the app to be unhidden, not necessarily foreground. Desktop also rejects hidden apps when validating a preview source. Native -10005 is not a permission diagnosis: preserve its message and distinguish capture failure from timeout.

fleet-computer-use uses the installed Codex native backend. computer_state and computer_action and computer_paste default to observation: "text": native capture is unchanged, but screenshot blocks are omitted from model output, including error responses. Use observation: "text_and_image" when the task needs visual verification or before coordinate click, scroll, or drag. On an action this option controls its result, not the validity of its input snapshot.

imageAvailable reports native image availability; imageDelivered reports whether the current response includes it. Coordinate actions require a fresh snapshot with imageDelivered: true. Requesting a visual state produces a new snapshotId and invalidates the previous one. Element actions remain available in text mode. An action returns its own native observation only. Fleet does not issue a second read, including after capture errors or incomplete Chrome observations: reads can activate apps or undo minimization. A usable native AX observation (wrapped state or the action's plain App/Window tree) yields a new snapshot; an acknowledgement without it yields observation: "unavailable" and snapshotId: null. Never repeat the action to obtain a snapshot. Request another computer_state explicitly only when necessary. Detailed action schemas remain version-cached and can be requested again with includeActionSchemas: true after context compaction.

Use computer_state({ app, fullTree: true }) after losing the previous AX context. This requires a standalone App/Window tree, not a diff: the current native MCP returns full trees without a disableDiff parameter. Fleet validates the response and returns computer_use_full_tree_unavailable with no snapshot if it cannot recognize a full tree. It makes one read, never replays cached trees or retries. This does not guarantee that an app exposes all of its content through AX.

computer_paste({ app, snapshotId, text, format, reason }) inserts at the already verified editable focus/selection. format is explicitly text, md, or html; Markdown is rendered to HTML, with the original source as the plain-text fallback. Formatting and paste support depend on the app. It uses native Command+V once, not type_text or whole-field set_value, and returns that action's observation and next snapshot without another read. Inspect the resulting content before submitting; a completed key action is not proof the app accepted the paste.

The paste helper keeps the previous clipboard items/types in process memory, not temporary files or logs. clipboardRestoration reports restored, preserved_newer_contents (another writer changed the clipboard), or failed. Refused calls can report not_touched; preparation failures can report unverified. It skips restoration when a newer clipboard change is detected; that check is best-effort, not atomic across apps. Restoration is best-effort on native failures and parent exit, not guaranteed after forced termination or OS errors. Clipboard backups above 64 MiB are refused before replacement.

All three tools default to allowActivation: false. A read-only macOS preflight refuses native dispatch unless the target is running, active, and has a focused, non-minimized window. This is a best-effort guard, not background execution: the native backend has no no-activation option and desktop state can race the check. allowActivation: true permits foreground use for that call only, including launch/activation/restoration; use it only when the task authorizes that effect, not as an automatic error fallback. Window addressing and cross-app snapshot reuse remain unsupported; the native element-ID lifetime is not established across apps.

Paste carries the call's explicit activation permission into the broker (default false). It checks readiness before clipboard preparation, checks the foreground app again immediately before replacing clipboard contents, and rechecks readiness before sending Command+V. A late refusal sends no paste key and attempts clipboard restoration; it returns actionOutcome: "not_started" with snapshotId: null. These checks are not atomic with native dispatch and do not bind a snapshot to a specific window. Do not treat them as protection against every same-app window change.

Computer Use diagnostic logs distinguish scope: "native_output" (raw backend response) from scope: "model_output" (final service response after projection and metadata). They record only text character counts, image counts/decoded bytes, timing, outcome and paste's effective activation permission—not screen text, image data, input text or reasons. These are payload measurements, not billed tokens; compare provider usage separately.

Security Notes

HTTP surfaces are loopback-only. Browser observer routes are directly available on loopback and terminal routes retain their Origin boundary (isTerminalAuthorized). MCP session tokens, bootstrap tokens, and selected absolute paths are not exposed through browser payloads, URL query strings, SSE frames, terminal tickets, logs, or static assets.

POST /theaters/folders/list and POST /theaters/folders/grants both require validateHost and isTerminalAuthorized. No adminToken or bearer auth is used for folder endpoints. Selected absolute paths appear only in list and grant API responses; they are not included in session, Theater, observer, or SSE payloads. When a Theater is registered, the resolved cwd is stored in durable local state (~/.fleet/console/state.json, sensitivity: "sensitive") exactly as before; this is a sensitive local file and is not transmitted to the browser.

Codex/Fleet Wiki routes preserve the migrated wiki security boundary: Host allowlist, Origin checks for write routes, loopback write gates, path containment, DOMPurify markdown sanitization, strict Mermaid rendering, and lockfile bearer auth for workspace registration.

Usage

fleet console
fleet console status
fleet console restart
fleet console stop

# transitional alias
fleet-console

Prefer fleet console. The transitional fleet-console bin still works. The launcher ensures the local console server is running and prints its /console/ address — free of browser token fragments — for you to open yourself; it never launches a browser on your behalf.

The AI Gateway is configured from the same launcher, against the same ai-gateway.json the Console screen edits:

fleet gateway                          # interactive configuration
fleet gateway status                   # configuration and credential state
fleet gateway models --json            # what the gateway currently exposes
fleet gateway auth login               # OpenCode Go / TypeSafe API keys
fleet gateway set xai-endpoint direct  # one policy axis, no prompts
fleet gateway serve                    # a standalone loopback gateway

The CLI writes the settings file directly, so it works with the Console stopped; an open Console tab shows the change after a reload. fleet gateway serve binds 127.0.0.1 and carries no authentication: a client sets ANTHROPIC_BASE_URL to the printed URL and any ANTHROPIC_API_KEY starting with sk-ant-, whose value the gateway never reads.

Desktop coexistence

Fleet Console Desktop is a thin Electron shell around this service, not a second Console implementation. The packaged shell embeds neither this package nor Node: it procures a checksum-verified managed Node runtime and installs this package under ~/.fleet/desktop/runtime/, then supervises this package's dist/cli.mjs serve as a sidecar process outside Electron and loads exactly http://127.0.0.1:<verified-port>/console/. The service remains the owner of HTTP/REST/SSE/WebSocket, PTY, provider policy, plugin runtime, durable JSON state, and the React UI.

Published stable CLI/browser and Desktop-supervised Console share one canonical stable lock and ~/.fleet/console durable-state namespace (unless the FLEET_CONSOLE_DATA_DIR override — formerly FLEET_CONSOLE_DIR, still accepted — is deliberately set). Owner metadata remains provenance/lifecycle compatibility data; it does not alter Console channel, health, update, or CLI-control behavior. Desktop adopts only a Console it launched itself; when another Console, such as one started with fleet console, already holds the lock, Desktop asks you to stop it and quits without touching it.

Updates apply in-session only to ordinary global packages through the npm-global worker. For a Desktop-managed console/latest runtime, POST /api/v1/updates/apply never mutates the live runtime: it answers delegated and hands the request to the supervising Desktop, which relaunches so its hardened entry-flow installer installs the new version. The /api/v1/pairing-identity endpoint is discovery only, never authentication.

Development

Source is split under core/host/ for the Node CLI/backend and core/client/ for the Vite React SPA. Agent, Terminal, and AI Gateway runtime implementations live under core/host/; their UI lives under core/client/src/. The private @fleet-console/sdk package under sdk/ is the shared plugin contract surface for core and built-in plugins.

pnpm --filter @dotobokuri/fleet-console dev
pnpm --filter @dotobokuri/fleet-console test
pnpm --filter @dotobokuri/fleet-console typecheck
pnpm --filter @dotobokuri/fleet-console build

build emits dist/fleet.mjs, dist/cli.mjs, dist/client/, and the remaining built-in plugin bundles. There is no external embed step.

See CLAUDE.md for ownership, token-boundary, and streaming invariants.