Install

iii trigger compose::add worker=console

This resolves the worker, writes its declaration to worker-compose.yaml, and reconciles the Compose project.

Quickstart

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
iii project init iii-app && cd iii-app
iii compose --up                 # engine on ws://127.0.0.1:49134

# New terminal, same folder
iii trigger compose::add worker=console # UI + /ws proxy on :3113
open http://127.0.0.1:3113

The browser hits / for the SPA shell and upgrades /ws to the engine WebSocket — one origin, no CORS, no API base URL to configure.

Bring up the chat stack

Chat runs on the harness durable turn loop. Its manifest declares the whole stack as dependencies — session-manager (the conversation store the sidebar, transcripts, and live token rendering are backed by), llm-router (generation + the model catalog), context-manager (the /compact summariser), approval-gate (human-in-the-loop approvals), and the provider workers — so a single command resolves and installs all of it:

iii trigger compose::add worker=harness

Add a provider key

The provider workers install with the harness, but they need credentials before any model appears — until then the model picker reads no models and chat won't generate. Add a key either way:

• In the UI (recommended) — open the model picker and use configure anthropic / configure openai to paste a key. It's written to that provider's slice of the llm-router configuration entry, and the catalog populates within seconds.
• From the environment — llm-router falls back to a provider's credential env var (e.g. ANTHROPIC_API_KEY), read in the router's own process. See llm-router for the credential model.

Pick a model in the composer and send — the turn streams back through the harness loop.

use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    let result = iii.trigger(TriggerRequest {
        function_id: "console::status".into(),
        payload: json!({}),
        action: None,
        timeout_ms: Some(5_000),
    }).await?;

    println!("{result:#?}");
    Ok(())
}

Why console

• One port, one binary. The React UI is baked into the executable with rust-embed, and the engine WebSocket is reverse-proxied at /ws on the same origin. No CORS preflight, no side-car static server, no dist/ directory to deploy. See src/assets.rs and src/proxy.rs.
• Live engine, live UI. Functions, models, traces, and chat sessions all stream over a single WebSocket via the iii browser SDK. Mention any registered function with @, switch models on the fly, and watch the trace appear in the panel next to you. See web/src/lib/iii-client.ts.
• Built for production. SIGINT and SIGTERM graceful shutdown (so docker stop and kubectl delete actually drain), URL credentials redacted from logs, immutable cache headers on content-hashed assets, and a fully self-contained binary with no runtime filesystem deps. See src/main.rs.

Features

Chat

A purpose-built agentic chat UI on top of Lexical. Lives in web/src/components/chat/.

• Two modes — ask and agent toggle right in the composer
• Live model picker — provider-grouped from router::models::list; static fallback (OpenAI, Anthropic, Google) when the catalog is unreachable
• @-mentions — fuzzy-search every function registered against the engine
• /compact slash command — summarises conversation history via the context-manager worker's context::compact, then persists a compaction custom session entry; the durable transcript is untouched — the marker renders from that entry and the summary anchors future turns
• Attachments — multi-file picker with text/image previews
• Function calls — running / pending / error cards; consecutive calls collapse to the latest and expand as one tight stack, while rich code/screenshot displays, approvals, and live calls stay visible; intermediate agent prose summarizes the completed batch; pending approvals use approve/deny gating (approval::resolve)
• Streaming — abortable mid-flight; live thought stream removed from the DOM on completion
• Markdown — GFM, code blocks with prism-react-renderer, syntax-highlighted JSON inputs and outputs
• Conversation sidebar — create, inline rename, delete, auto-title from the first message
• Context-usage meter — token estimate with warn / danger thresholds and a /compact nudge
• Session ID — copyable, deep-links every conversation into the trace explorer via iii.session.id
• Persistence — conversations, active id, last model, sidebar state — all in localStorage

Traces

Full-fledged OpenTelemetry explorer over engine::traces::* and engine::logs::list. Lives in web/src/pages/TracesV2/.

• Live timeline strip masthead — every span streamed in real time, with a shared funnel as the volume control
• Two detail visualizations — lane timeline (same visual grammar as the strip) and a waterfall tree virtualized for huge traces
• Rich filtering — status, time presets, min/max duration, arbitrary attribute key/value pairs, debounced free-text search, saved views
• Group by — server-side aggregation with lazy per-group member expansion
• Span detail tabs — info, attributes, events, errors, OTel logs, context (baggage), links
• Live streaming — spans append over iii streams (iii:devtools:*) instead of polling; one seed read, then append

Worktrees

The human window into the worktree worker: parallel agent checkouts, ownership, and land outcomes. Lives in web/src/pages/Worktrees/ and web/src/components/chat/. The whole surface is presence-gated: it appears only while the worktree worker is connected to the engine (the nav entry and picker tab hide; a direct #/worktrees hit lands on an install notice).

• Graph page (#/worktrees) — repo, worktree, and owning-session nodes from worktree::list { include_status: true }, refreshed live off all six worktree::* lifecycle trigger types (poll fallback while bindings are unavailable), with a per-worktree detail panel: branch, base, advisory dev port, clean / ahead / behind, diffstat, and the integrated marker for squash- or rebase-landed branches
• Picker tab — the chat working-directory picker grows a worktrees tab next to directory browsing: picking a managed worktree validates the path and claims it for the conversation's session; the console-made claim auto-releases when the conversation points elsewhere (best-effort; the worker's prune sweep is the durable backstop). Worktrees with a land in progress are listed but not retargetable
• Working-dir badge — a conversation rooted in a managed worktree shows branch, short id, dirty * / ahead +n indicators, and a lifecycle dot instead of the plain path chip; the raw path stays reachable as the tooltip
• Live land notices — worktree::landed / worktree::land-blocked events surface in the chat as notices (target branch and merged sha, or the block reason and conflicted files) and refresh the badge

Memory

The human window into the memory worker: named banks of always-injected markdown rules and auto-extracted memories. Lives in web/src/pages/Memory/. Presence-gated like Worktrees: the page appears only while the memory worker is connected (a direct #/memory hit lands on an install notice).

• Bank rail — every bank with live memory / pinned / rule counts and inline create
• Rules tab (first) — the bank's markdown rules as in-place editors (save appears only on edit; delete asks to confirm); the agent appends learned standing instructions to the auto-managed learned rule as you correct it in chat
• Memories tab — server-paged newest-first list with pin / edit-in-place / tombstone delete, a show-history toggle, and search that runs memory::recall (the ranked scorer, not a client filter)
• Graph tab — entity hubs with memories as spokes: level-of-detail for large banks, draggable nodes, wheel zoom/pan, click a node for an inspect card
• Preview tab — the whole turn before it happens: memory::preview composes the exact system-prompt rules section and the appended memories (ambient floor + budgets applied) for a hypothetical question, with clickable example questions from the bank's own content
• Live — the page re-reads off memory::item-changed / memory::bank-changed (poll fallback), so memories appear the moment they're learned
• In chat — a bank picker in the composer (session metadata memory_bank) and a memory chip on each assistant reply naming the bank, how many rules and memories fed the turn, and whether recall ran semantic; click it to expand the exact records

Live catalogs

The composer's @-mentions and the model picker pull from the engine in real time.

• engine::functions::list — TTL-cached function list (VITE_FUNCTIONS_LIST_CACHE_MS, default 10s) → web/src/lib/functions-catalog.ts
• router::models::list — provider-grouped model catalog, refreshed live off the router::models::changed trigger type → web/src/lib/models-catalog.ts

Theming

Light and dark themes via data-theme + CSS custom properties. Persisted to localStorage with an inline init script in index.html to prevent flash-of-wrong-theme on first paint.

Worker SDK surface

console registers a health probe for iii worker info smoke tests, plus the workspace functions that let an agent show the human a screen next to the conversation:

A screen is chat, chat:, traces, workers, or ext: for a worker page (ext:shell, ext:browser, ext:editor, ...). Call open with { screen: "chat", session_id: "" } to open a panel pinned to one conversation; the structured input is persisted as chat:, and opening that exact session again reuses its existing panel. The workspace layout is the workspace section of the console configuration entry, so every browser pointed at this engine picks the change up. open stays on the active tab when it already shows the screen, else switches to the tab that does, else places the screen beside chat in the active tab (adjacent empty column, any empty column, new column), else opens a fresh tab; placement reports which (existing, empty_column, new_column, new_tab). It never replaces a mounted screen. close detaches the screen everywhere it is mounted and is idempotent; pass the same screen: "chat" and session_id to close one pinned conversation panel. Unknown screens fail with WORKSPACE_INVALID_SCREEN; an unreachable configuration worker with WORKSPACE_UNAVAILABLE.

Defined in src/functions/status.rs and src/functions/workspace.rs.

Architecture

flowchart LR
    Browser["Browser SPA<br/>(iii-browser-sdk)"] -->|"HTTP GET /"| Console
    Browser -->|"HTTP GET /runtime"| Console
    Browser -->|"WS /ws"| Console
    Console["console binary<br/>(axum + rust-embed)"] -->|"WebSocket"| Engine["iii engine<br/>:49134"]
    Console -. "registers console::status, console::workspace::*" .-> Engine

console is a thin HTTP server. It serves the embedded SPA bundle and runtime connection settings, hosts injected worker UI assets, and transparently proxies /ws to the iii engine. The browser only ever talks to one origin.

Configuration

Console registers a console entry with the central configuration worker. Its http_port value is authoritative after first registration: Console reads it before binding, watches configuration:updated, and moves the listener live when the port changes. The replacement port is bound and started before the old listener is gracefully drained; a failed bind keeps the previous listener and port active.

The local config.yaml is a first-registration seed and a fallback for direct runs where the configuration worker is unavailable:

http_port: 3113       # initial port seed for the UI + /ws (default: 3113)
injectable_ui: true   # kill switch for runtime-injected worker UI (default: true)

The configuration entry also stores UI preferences and injectableUi.disabledWorkers. Port and per-worker UI changes apply without a Console restart; the local injectable_ui kill switch remains startup-only.

CLI flags

Routes

The SPA bundle is embedded into the binary at compile time via rust-embed — the released console has no separate dist/ directory, no side-car asset server, and no runtime filesystem dependency for the UI.

Injectable UI

Workers extend the console at runtime — whole pages, function-trigger renderers, and layered trigger-activity renderers as plain React components sharing the console's React instance (spec: iii/tech-specs/2026-07-17-injectable-ui). The console owns three trigger types:

The trigger's function_id is the worker's content function ({path} → {content, content_type?}); the console fetches over the bus, hashes, serves from /ui/*, and pushes invalidations so every open tab disposes the old module and re-imports the new one. Injected scripts default- export setup(host) and register through host.pages (whole pages at #/ext/), host.functionTriggers (function-trigger message renderers — injected renderers dispatch before the built-in families, so matching a built-in id overrides it; metadata.display promotes the winning renderer's rich result into the collapsed chat flow), host.triggerRenderers (override the compact timeline display, expanded details, source section, and raw-data redaction for normalized registration/fired/retirement activities, with host fallbacks for every slot), and host.configForms (replace the workers-tab form region for one configuration id; dirty/save/reset stay host-owned). A configuration form can opt into { layout: 'full' } to receive the entire available editor width and height; contained layout remains the default. Renders are fenced by an ErrorBoundary and scoped under data-iii-ui="". console::ui-manifest (internal) lists the loadable assets. The state worker's ui/ directory is the broad delivery reference; cron/ui/ is the trigger-activity renderer reference.

Tech stack

cd web && pnpm install && pnpm build && cd ..
cargo build --release

cargo test                          # unit + manifest + e2e (e2e self-skips if `iii` isn't on PATH)
cd web && pnpm test                 # vitest
cd web && pnpm typecheck && pnpm lint

License

Apache 2.0 — see LICENSE.