@theruansilva/omp-web

v2.4.0

Published

17 days ago

Web UI for Oh My Pi Coding Agent

OMP WEB

OMP WEB is a web UI for Pi Coding Agent that keeps agent sessions running in real workspaces on your machine or server.

Run agents where your code, tools, credentials, and build caches live. Supervise them from any browser.

Website and docs: https://omp-web.dev/

OMP WEB desktop screenshot

Why OMP WEB?

Agentic development works better when the work environment is persistent.

OMP WEB lets you:

keep Oh My Pi Coding Agent sessions alive after browser disconnects;
run agents inside real repositories and git worktrees;
supervise multiple sessions in parallel;
switch between laptop, phone, tablet, and desktop;
use a server, workstation, or remote dev box as your agent runtime;
manage projects, workspaces, files, terminals, sessions, and remote machines from one web UI.

Your browser is the control surface. The work stays where it can keep running.

Quick start

Requirements:

Bun 1.1 or newer
Oh My Pi Coding Agent configured for your user
git and the development tools your agents need

Install and start OMP WEB as per-user services:

bun install -g @theruansilva/omp-web
omp-web install
omp-web doctor

Then get your auth token and open the web interface:

# View your generated authentication token
cat ~/.omp-web/auth-token

Open:

http://127.0.0.1:8504?token=<YOUR_TOKEN>

(If you navigate to http://127.0.0.1:8504 without a token, enter your token into the Unlock screen).

Useful commands:

omp-web status
omp-web logs
omp-web restart
omp-web doctor
omp-web version
omp-web uninstall

For more install options, including one-line install, Pi package install, WSL/manual usage, and remote access, see the installation guide.

Core model

OMP WEB organizes work like this:

Machine     a local or remote OMP WEB runtime endpoint
Project     a folder on that machine
Workspace   a git worktree, or the project folder for non-git projects
Session     a Pi Coding Agent chat running inside a workspace

A typical flow:

Add a project.
Choose a workspace or git worktree.
Start a session.
Let the agent work.
Come back later from any browser.

Remote-first development

OMP WEB is designed for remote AI-driven development.

Instead of tying agent work to your laptop session, run OMP WEB on a machine that stays available: a server, desktop, cloud VM, home lab machine, or remote dev box.

Use a private network, SSH tunnel, trusted reverse proxy, or federated OMP WEB machine setup when accessing it remotely.

Machines and fleets

OMP WEB can register other OMP WEB runtimes as remote machines. One browser-facing OMP WEB instance can proxy projects, files, git state, sessions, terminals, activity, Pi package management, and selected-machine settings from trusted remote machines.

When a remote machine is selected, Settings tabs label their target. Pi packages, OMP WEB plugin enablement, session daemon toggles, external file access, and upload defaults target the selected machine. Gateway/server settings such as host, port, allowed hosts, registered machines/tokens, and keyboard shortcuts stay local to the gateway/browser.

Plugins

OMP WEB supports trusted browser-side OMP WEB plugins that can add actions, workspace panels, and workspace metadata.

Pi packages are managed separately through Pi's package manager or Settings → Pi packages. In a federated setup, the Pi packages panel targets the selected machine and labels where installs, updates, or removals will run. Use Settings → OMP WEB plugins to enable or disable discovered browser plugins on the selected machine.

After installing, updating, or removing a Pi package, type /reload in each idle OMP WEB session on that machine to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for newly discovered or changed OMP WEB plugins.

Configuration

Global config lives at:

$OMP_WEB_CONFIG
~/.config/omp-web/config.json

Project-local OMP WEB config lives at:

<project>/.omp-web/config.json

Common configuration includes host/port, path access, uploads, OMP WEB plugin enablement, shortcuts, and session daemon options. In Settings, machine-affecting config targets the selected machine; gateway host/port/allowed-hosts, remote machine registration, tokens, and keyboard shortcuts stay local.

Authentication

Starting with v2.3.0, OMP WEB requires token-based authentication by default to protect browser access, WebSocket streams, and API endpoints.

Automatic token generation: On startup, OMP WEB generates a cryptographically secure token and saves it to ~/.omp-web/auth-token (with 0600 permissions).
Browser access & unlock screen: Visiting http://127.0.0.1:8504?token=<YOUR_TOKEN> validates the token and sets a secure HttpOnly cookie (omp_web_token). If you open the bare URL, an Unlock screen prompts for the token.
API and WebSockets: Authenticate using the Authorization: Bearer <YOUR_TOKEN> header, the omp_web_token cookie, or the ?token=<YOUR_TOKEN> query parameter.
Custom token: Configure "authToken": "your-token" in ~/.config/omp-web/config.json or export OMP_WEB_AUTH_TOKEN="your-token".
Disabling authentication: If running behind a trusted reverse proxy or private network, you can disable authentication with "authRequired": false in ~/.config/omp-web/config.json or by setting OMP_WEB_AUTH_REQUIRED=0 (or "false").

Development

Clone the repository and run:

bun install
bun run dev

Open the Vite URL, usually:

http://localhost:8505

For the split development setup:

bun run dev:sessiond
bun run dev:web
bun run dev:client

Validate changes with:

bun run verify

Security model

OMP WEB assumes trusted users, trusted repositories, and trusted server paths.

It is not a sandbox, permission system, or multi-tenant platform. Do not expose it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme