English | 简体中文
Run omp sessions on your own machines and manage them from a browser. A small outbound-only agent on each machine connects to the hub; the hub serves the dashboard, encrypted-session relay, and web client.
A tiled workspace. Tabs combine chats, terminals and files from multiple sessions. Overview, Machines and Saved history remain available without replacing the workspace's live views.
Read the conversation first. The sidebar keeps session status visible; Tasks, Agents and Context share an on-demand inspector beside the transcript.
These captures use an isolated machine and synthetic saved history through the real SDK; no external provider, personal session history or credentials appear.
| Package | Runs where | Purpose |
|---|---|---|
packages/hub |
server or Docker | Relay, machine/session API, web UI and agent control channel |
packages/agent |
each machine you control | Outbound-only daemon that hosts isolated omp sessions |
packages/web |
served by the hub | Desktop and mobile browser UI |
packages/im-hub |
optional connector beside the hub | Feishu bot connection, authorized IM commands and session-scoped MCP channels |
No TUI opens on an agent machine. Use the browser or attach a terminal with omp join "<full or view link>".
- Shared workspace: The tiled workspace (
/), Overview (/overview), Machines (/machines), Saved history (/history), sessions and machine usage share one frame. Start in a side sheet with machine, directory and prompt; Advanced reveals profile, name, tools and superagent controls. Namespace assignment requires explicit transcript-sharing consent. Open agents from the sidebar or Ctrl+K; mobile navigation has separate Agents and Files tools. Session menus separate rename/hide from confirmed stop/delete and strict revival. Stop retains the Hub record, and saved omp files also survive deletion. Search lists/history by metadata and prompt/assistant text. - Work in the browser: Stream transcripts and tool results, upload files,
send or interrupt prompts, answer interactive dialogs and manage subagents.
Choose Answers or Full details in Browser settings → This browser → Display
→ Transcript view, not inside the transcript. Answers keeps running/failing
work visible and successful work expandable; Full details restores the complete
transcript. The choice persists in this browser and applies to all conversations,
including
/joinand subagents, without changing agent behavior. A compact task summary opens the shared Tasks/Agents/Context inspector, docked only when space permits. Model, thinking and context controls sit next to the responsive composer. Full-control and view-only links can attach an omp client; sharing starts view-only and link credentials stay hidden until explicitly revealed. The plug icon and count open a live list of connection names, host/client roles and interaction permissions. The count includes the session host and this browser; it counts connections, not people or agents. - Tiled panes: Each workspace tab can mix chats, terminals and UTF-8 file
previews/editors from different sessions. Split right/below, resize, maximize,
drag panes to edges or tabs, or use the pane menu's Move to tab action.
Chat splits stay beside the originating pane in its tab, including after legacy
migration; an already-open chat moves there rather than switching to its tab. Closing
a chat closes only its view; closing a terminal requires confirmation and ends
its shell. Moving panes preserves composers, edit buffers and terminal instances.
Chat identity, connection state and pane controls share one header. Narrow panes
collect session actions and secondary status in menus; machine/cwd details
remain available on demand, and maximize is available in the pane menu.
Hover or keyboard-focus the tab/pane controls for shortcut tooltips with
monospace keycaps (
⌥/⇧on macOS,Alt/Shiftelsewhere). Workspace shortcuts share Alt+Shift: W/Q create/close a workspace tab, C adds a chat, D/E split right/below with chat, J/K focus the next/previous pane, M maximizes/restores, and X closes the focused pane. Browser Ctrl/⌘ shortcuts and F6 keep their native behavior. Workspace shortcuts pause in dialogs and menus; closing terminals or unsaved files still asks first. The file tree stays in the left agent manager and can follow focus or be pinned to an agent. Single-click files for reusable previews; double-click, Pin or Edit to keep them open. Unsaved edits are never replaced by another preview, and saves check the file version before writing. Transcript file references and copied session-specific links open the correct file and line range. Layout metadata is saved per browser, migrating old per-session arrangements. Drafts remain in memory, not localStorage. Terminals retain their originating session/run identity; after a different run starts, explicitly open a new terminal. Browser reconnects can reattach to a surviving shell with recent output, not restore a process after session/daemon exit or a daemon-Hub disconnect. Files and terminals still require the root Hub token, a live non-Task session and an agent 0.18.0+; collab links grant neither. No daemon upgrade is needed for this UI cutover. Use HTTPS/WSS outside loopback. See workspace protocol. - Extension display: Plugin
setStatustext and string-arraysetWidgetcontent appear around the browser composer, including read-only links and input dialogs. Updates/clears are live and reconnects replay current state. Terminal colors are stripped; TUI component factories and custom editors are not mirrored. Requires the patched agent; restart upgraded daemons. - Consistent UI: Tailwind v4 semantic tokens and shadcn Base UI components provide light/dark themes, focus-visible states and keyboard-safe dialogs.
- Control the agent: Choose models, thinking level and role assignments; use session-scoped advanced settings, modes (plan, advisor, goal and loop), and MCP servers (config edits apply to new sessions). At start, optionally whitelist tools or enable superagent fleet controls scoped to a required namespace; superagents use fleet-only tools to start, stop and message other sessions. An empty whitelist keeps the default tool set for ordinary sessions.
- Model presets:
/modelpresetsaves and applies named role-model/default-thinking configurations on the agent machine, with searchable details, source badges and configuration-shadowing warnings. Supportslist,save <name>,switch <name>anddelete <name>; requires the 0.16.0 agent (SDK 18.4.9) and a daemon restart. Browser Recent model selections remain separate. - Find fleet evidence: Superagents can search their namespace's live and terminal
transcripts, including tool arguments/results, with time, role, tool, source and
argument-field filters. Read a hit directly with
fleet_get_message, including nonadjacent paired results and continuations of long output. Global pages have snapshot cursors and explicit partial coverage; see the fleet protocol. Namespace search/context requires agent 0.15.0+; restart upgraded daemons to load it. - Fleet IRC and strict revival (0.17.0): Operators and explicitly enabled
workers exchange durable agent chat; cross-namespace communication needs
directed grants, not claim. Replies and processing acknowledgments are explicit;
accepted, saved and processed are distinct. A live operator can restore its
controlled worker's original identity/history, or a same-namespace operator
when the namespace policy permits it. Chat never grants control or cross-group
revival. Browser controls configure grants/capabilities and show recovery state.
The creation sheet exposes IRC opt-in (workers off, superagents on by default
when supported); Machines owns namespace policies and directional grants.
Strict revive opens the confirmed Manage flow and never silently starts fresh.
Enable
FLEET_IRC_ENABLED=1/FLEET_REVIVE_ENABLED=1separately (default off), persistHUB_STATE_FILEplus its fleet SQLite sibling, and restart upgraded 0.17.0 daemons. SDK remains 18.8.7; no new SDK patch. See protocol §9 and the recovery runbook. - Operate the fleet: See machine usage and restart an agent daemon from the dashboard to load
new code: its session children stop and resume
8000
from saved transcripts under their existing IDs.
The authenticated hub restart API hands over machine/session records from
hub-state.json(the real hub's default state file). Agents reconnect and live hosts recreate relay rooms; rooms and ephemeral notices are not persisted, so allow for an interruption. - Chat through Feishu: the optional IM hub reuses one enterprise self-built bot
across isolated sessions.
/sessions,/new,/use,/to,/status,/canceland/stopare handled locally; ordinary messages enter the SDK through MCP notifications. Explicit replies andaskdialogs return to their original chat even after switching sessions. Requires 0.17.0 hub/daemon and explicit actor/project authorization. Web Settings → Feishu / IM guides project selection and official app-authorization QR; secrets stay server-side. See the connector guide.
┌────────────┐ WSS /agent (token) ┌──────────────────────────────┐
│ omp-hub- │ ───────────────────▶ │ HUB │
│ agent (per │ │ relay /r/:room (WS) │
│ machine) │ ◀── start {cwd} ──── │ API /api/* (Bearer) │
└────────────┘ │ web /* (static UI) │
│ spawns per session └──────────────────────────────┘
▼ ▲ ▲
┌────────────┐ collab E2E frames ┌─────────────┴───┐ ┌────┴─────────┐
│ session- │ ──────────────────▶ │ browser (web UI)│ │ omp join │
│ host (SDK) │ ◀── prompt/abort ── │ guest (full │ │ (TUI attach) │
└────────────┘ │ write link) │ └──────────────┘
└─────────────────┘
- Session frames are AES-256-GCM end-to-end encrypted between host and browser or
omp join; the relay forwards ciphertext. The hub registry nevertheless holds full/view links and their keys, and its state snapshot stores those links on disk. Treat both hub and snapshot as sensitive. - The agent dials out to the hub and requires no inbound port on the controlled machine.
The Hub runs on Bun ≥ 1.3.14; the source agent requires Bun ≥ 1.4.0 for its confined SQL transcript-query worker. The compiled native agent bundles its own runtime. An agent machine needs working omp provider credentials (~/.omp/agent or provider API keys). The published releases provide a source archive with the hub, already-built web UI, agent source and third-party licenses; it contains neither node_modules nor Docker build files. These examples use the v0.15.0 assets. For changes made after that tag, use the source checkout below.
# On the hub machine, from any working directory:
mkdir -p "$HOME/omp-hub-release" && cd "$HOME/omp-hub-release"
umask 077 # keep hub-state.json and its session links private
curl -fL -O https://github.com/KamijoToma/omp-hub/releases/download/v0.15.0/omp-hub-v0.15.0.tar.gz
curl -fL -O https://github.com/KamijoToma/omp-hub/releases/download/v0.15.0/SHA256SUMS.txt
sha256sum -c --ignore-missing SHA256SUMS.txt
tar -xzf omp-hub-v0.15.0.tar.gz
cd omp-hub
HUB_TOKEN=dev-token HOST=127.0.0.1 bun packages/hub/src/main.tsIn another terminal, repeat the download, checksum and extraction steps on each agent machine (or reuse the extracted directory for a local trial), then run:
cd "$HOME/omp-hub-release/omp-hub"
bun --cwd=packages/agent install --frozen-lockfile
mkdir -p /tmp/omp-hub-demo
HUB_TOKEN=dev-token bun packages/agent/src/main.ts --hub ws://127.0.0.1:8080 --name dev-machineOpen http://127.0.0.1:8080, enter dev-token, choose dev-machine and start a session in /tmp/omp-hub-demo. dev-token and plain HTTP/WS are only for a local, loopback-only trial. For a remote deployment, choose a strong shared token and expose the hub over HTTPS/WSS:
# Hub machine, from the extracted omp-hub/ directory; cert paths must be readable.
cd "$HOME/omp-hub-release/omp-hub"
HUB_TOKEN='<strong-shared-secret>' HOST=0.0.0.0 \
HUB_TLS_CERT=/path/to/cert.pem HUB_TLS_KEY=/path/to/key.pem \
bun packages/hub/src/main.ts
# Agent machine, from its extracted omp-hub/ directory, after the locked install:
cd "$HOME/omp-hub-release/omp-hub"
HUB_TOKEN='<same-strong-shared-secret>' \
bun packages/agent/src/main.ts --hub wss://hub.example.com:8080 --name my-machineReplace the example secret, certificate paths and DNS name; restrict hub ingress to trusted networks. Alternatively terminate TLS at a reverse proxy and set HUB_PUBLIC_URL=https://hub.example.com on the hub so generated session links use WSS. A remote browser needs HTTPS for WebCrypto; remote insecure ws:// links are rejected. Keep full links private: they grant write access. The agent's frozen lockfile installs platform-specific prebuilt SDK binaries; no sibling SDK checkout or Rust build is needed. See agent setup.
On Linux x64 (glibc), the native Agent archive does not require Bun. Download it on the
controlled machine and keep all five executables and pi_natives.linux-x64-baseline.node together.
The daemon spawns the isolated session host, statistics, subscription and SQL-query workers from that directory:
mkdir -p "$HOME/omp-hub-agent" && cd "$HOME/omp-hub-agent"
curl -fL -O https://github.com/KamijoToma/omp-hub/releases/download/v0.15.0/omp-hub-agent-linux-x64-v0.15.0.tar.gz
curl -fL -O https://github.com/KamijoToma/omp-hub/releases/download/v0.15.0/SHA256SUMS.txt
sha256sum -c --ignore-missing SHA256SUMS.txt
tar -xzf omp-hub-agent-linux-x64-v0.15.0.tar.gz
HUB_TOKEN="<same secret as the hub>" ./omp-hub-agent --hub wss://hub.example.comThe native agent needs the machine's omp auth store (~/.omp/agent) or provider credentials,
but no Bun, npm installation or source checkout. Use ws:// only on a local loopback hub.
From a terminal with Git and Bun installed, clone the repository and run from its root (the release archive has no web source/build scripts):
git clone https://github.com/KamijoToma/omp-hub.git
cd omp-hub
bun --cwd=packages/agent install --frozen-lockfile
mkdir -p /tmp/omp-hub-demo
umask 077 # keep hub-state.json and its session links private
HUB_TOKEN=dev-token HOST=127.0.0.1 bun --cwd=packages/hub run demo
# In another terminal, also from the repository root:
HUB_TOKEN=dev-token bun --cwd=packages/agent run start -- --hub ws://127.0.0.1:8080 --name dev-machinedemo installs the web's locked dependencies, builds its static UI and launches the hub. Normal bun --cwd=packages/hub run start serves an existing web build. To attach a terminal client, copy a session's link and run omp join "<paste link here>".
The web package uses Tailwind v4 and shadcn's Base UI Nova components
(packages/web/components.json). bun --cwd=packages/web run dev loads the
Tailwind plugin from bunfig.toml; bun --cwd=packages/web run build runs the
same plugin explicitly through scripts/build.ts. Demo, CI, release and
Docker builds all use that build command. Add theme roles in
src/styles/tokens.css, not separate page palettes.
From the repository root, build the hub/web image and expose its port on loopback:
docker build -f docker/Dockerfile -t omp-hub .
export HUB_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 -e HUB_TOKEN="$HUB_TOKEN" \
-e HUB_STATE_FILE=/tmp/omp-hub-state/hub-state.json omp-hubCompose also uses the exported token; configure a writable HUB_STATE_FILE in its container environment before running docker compose -f docker/docker-compose.yml up --build. The agent is not in this image; install and run it on each controlled machine. The image build needs repository web source and docker/, which are not in the release archive. For remote access use HTTPS/WSS as above; the image listens inside the container on all interfaces but this example only publishes on the host's loopback. Mounted TLS keys must be readable by the non-root container user. The example's /tmp state is disposable: mount a private writable directory and set HUB_STATE_FILE there for recovery across containers. Do not use the root-owned /app default as a writable state location. See TLS / LAN notes.
HUB_TOKEN is required for the agent connection and HTTP API; an empty token prevents hub startup. The browser stores it locally. Any token holder can obtain full session write links, browse recent omp session history across projects (including paths, titles and first-message excerpts), and resume saved sessions. Headless session hosts auto-approve omp tool use and can access the agent machine's files and provider credentials; a tools whitelist limits one session's available tools, not what a trusted token holder can start next. A superagent has fleet-wide session controls. Use a dedicated OS account for each agent when local history or credentials need isolation.
The relay /r/ does not authenticate peers or enforce room quotas/host identity: even a view-link holder could claim a room's host role after a disconnect. The hub's live registry and hub-state.json snapshot contain session keys; protect the state file, token and links. The real hub entry persists machine/session registry snapshots for restart recovery, but live relay sockets and ephemeral notifications do not survive a process restart. Agent and guest reconnects can restore live rooms; do not treat this as a zero-interruption guarantee. This is not a public-internet or multi-tenant service: restrict access to trusted users and networks. See the security model.
- docs/architecture.md — components, topology, security model, design decisions
- docs/protocol.md — wrapper↔hub control protocol, HTTP API, relay contract
- docs/milestones.md — MVP phases and post-MVP roadmap
- docs/e2e.md — manual end-to-end verification and known limitations
GitHub Actions runs frozen installs, typechecks and Bun tests for all three packages, then builds the web UI, hub-only container and Linux x64 native Agent bundle. Every push exercises the unpacked native Agent against a live session, named-profile statistics and daemon restart; a qualifying tag repeats this after artifact download, adds both archives and checksums to the GitHub Release. Releases contain the tagged version, not unreleased source changes; no npm package or Docker image is published by this workflow.
MIT. The vendored web client derives from
@oh-my-pi/collab-web (MIT); the original copyright
holders and permission notice are preserved in LICENSE.
Bundled third-party libraries keep their own licenses (including Lucide's ISC/Feather notices
and Marked's Markdown notice); the hub Docker image carries their full texts in /app/licenses/,
and the GitHub release archive in licenses/.
The source tree includes a disabled-by-default Task API for finite-budget coding
jobs in registered digest-pinned rootless Podman/Docker runtimes. Tasks appear as
ordinary Hub sessions: automatic view is read-only, explicit manual takeover and
resume preserve the original deadline, and terminal results retain immutable
artifacts/history. Strict model gateway accounting covers real paid attempts;
unknown usage retains reservations. Current adapter supports zai/glm-5.3-flash,
not strict USD invoice caps.
Start with the operator catalog/deployment guide and API/wire contract. Actual E2E evidence records real Podman/GLM success and a failed debug-provider call without hiding its retained reservation. This source feature is not a claim that existing release archives or production deployments include it; implementation status lists verification caveats.