SAGE OPC UI

Standalone browser UI for the SAGE One-Person Company (OPC) control plane. It discovers application entry scripts, validates launch contracts, starts and observes real processes, runs representative requests, and displays runtime logs, compatibility probes, operator metrics, queue pressure, and DAG edges.

The repository includes a Python bridge that serves this UI and loads the real control-plane API from the sibling sage-examples repository. Managed applications and control-plane implementation remain in sage-examples.

Validated repository branches

The current ICPP demo has been validated with this exact branch combination:

Repository	Branch	Role
SAGE	icpp-demo	Core SAGE runtime
sage-examples	icpp-demo	OPC API, managed apps, and runtime metrics
sage-opc-ui	main	Standalone browser UI

Do not assume that the main branches of SAGE or sage-examples contain the same OPC and demo changes. No branch merge is performed by the startup instructions in this README.

What is and is not included

This repository contains:

• index.html: page structure.
• app.css: visual system and responsive layout.
• app.js: API client and browser interactions.
• config.js: deployment-specific OPC API origin.
• backend/opc_ui_server.py: one-process bridge for the real OPC API and UI.

There is no package manager, build step, generated bundle, or Node.js runtime dependency. Do not run npm install. The bridge does not duplicate a mock backend: it imports opc.server.create_app from the selected sage-examples checkout, so discovery, launch, invocation, metrics, and logs use the actual OPC runtime.

The repository does not contain the OPC API, SAGE runtime, application examples, model servers, or application datasets.

Requirements

Browser UI

• A modern browser with JavaScript, fetch, CSS Grid, and IntersectionObserver.
• Clipboard actions require localhost, HTTPS, or another browser-approved secure context. The rest of the UI does not depend on clipboard access.

Control-plane backend

• Sibling repository: /root/SAGE/sage-examples.
• SAGE Conda environment: /root/miniconda3/envs/sage.
• Python 3.10 or newer; the current environment uses Python 3.11.6.
• The backend imports fastapi, httpx, pydantic, and uvicorn.

The backend dependencies are formally declared by the opc optional dependency in the sage-examples icpp-demo branch. For a fresh checkout:

cd /root/SAGE/sage-examples
/root/miniconda3/envs/sage/bin/python -m pip install -e ".[opc]"

The versions validated in the current development environment are:

Package	Validated version
fastapi	0.135.2
httpx	0.28.1
pydantic	2.13.2
uvicorn	0.42.0

Verify the required environment before starting either service:

ssh server4-lj
cd /root/SAGE
/root/miniconda3/envs/sage/bin/python --version
/root/miniconda3/envs/sage/bin/python -c \
  "import fastapi, httpx, pydantic, uvicorn; print('OPC backend imports: OK')"

Managed applications can have additional app-specific Python, data, GPU, or service requirements. The launch preflight and compatibility views expose those requirements when the application declares them.

Optional model services

The static UI and the core OPC catalog do not call model services directly. Applications that require generation or embeddings use the services configured by sage-examples. In the current SAGE development environment, the existing services are:

• LLM API: http://11.11.11.32:8000
• Embedding API: http://11.11.11.32:8001

These services are managed externally. Do not start, stop, or reconfigure them from this repository.

Ports and network path

Port	Purpose
18400	Combined OPC control-plane API and /ui/
18000-18100	Managed application port pool
18005	Recommended fixed port for the ICPP Ticket Triage demo

The bundled UI and API are same-origin in the recommended bridge deployment. The browser also talks to any application UI that the operator opens. Consequently:

• A remotely hosted application UI needs its own reachable or forwarded port.
• Separate frontend deployments must configure config.js and backend CORS.

Configure a separate static deployment

The combined bridge configures the API origin automatically. Only copy or edit config.js when serving the static files separately:

window.SAGE_OPC_CONFIG = {
  apiBaseUrl: "http://127.0.0.1:18400",
};

The value must be an origin without a trailing path. Do not place tokens, passwords, or application secrets in this file.

Start the combined demo

All SAGE commands run on server4-lj under /root/SAGE with the required sage Conda environment.

The bridge defaults to the sibling path /root/SAGE/sage-examples, but the path is explicit below so the branch dependency is unambiguous:

ssh server4-lj
cd /root/SAGE/sage-opc-ui
/root/miniconda3/envs/sage/bin/python backend/opc_ui_server.py \
  --host 127.0.0.1 \
  --port 18400 \
  --workspace-root /root/SAGE/sage-examples \
  --python-executable /root/miniconda3/envs/sage/bin/python \
  --port-range-start 18000 \
  --port-range-end 18100

This command serves:

• UI: http://127.0.0.1:18400/ui/
• API health: http://127.0.0.1:18400/api/health
• API documentation: http://127.0.0.1:18400/docs

Check both sides of the bridge:

curl -fsS http://127.0.0.1:18400/api/health
curl -fsS http://127.0.0.1:18400/api/settings
curl -fsS http://127.0.0.1:18400/ui/ | head

Forward remote ports

When the browser runs on the local workstation, create a separate local terminal tunnel:

ssh -N \
  -L 18400:127.0.0.1:18400 \
  -L 18005:127.0.0.1:18005 \
  server4-lj

Then open http://127.0.0.1:18400/ui/.

The 18005 forwarding is needed only when the demo application exposes its own browser UI on that fixed port. If auto-port allocation chooses a different port, forward that port too or relaunch with a fixed port.

Validated ICPP demo path

The catalog currently reports 104 discovered entry scripts and 3 end-to-end verified launch contracts:

• data_cleaner
• supply_chain_alert_api
• ticket_triage_api

“Discovered” means that OPC found and introspected an entry script. It does not mean that every entry has passed the same end-to-end launch verification.

Recommended live flow:

1. Search for Ticket Triage API.
2. Select Launch, disable auto-port allocation, and set port 18005.
3. Run Dry Run and show the preflight checks.
4. Launch the application.
5. Run Demo Flow.
6. Open Metrics to show the ten-stage operator DAG, throughput, P95 latency, queue wait/depth, and run-to-run comparison.
7. Open Compatibility and Logs.
8. Stop the instance.

This flow uses bundled deterministic demo data and does not require the LLM or embedding services.

Troubleshooting

The header shows API unavailable

• Confirm curl http://127.0.0.1:18400/api/health on the remote server.
• Confirm local port 18400 is forwarded when the browser is local.
• Confirm the browser opened /ui/ on the same 18400 origin.

The page loads but API requests are blocked

The OPC backend CORS origin must exactly match the UI origin, including scheme, host, and port. Repeat --allowed-origin when multiple origins are required.

Open App UI does not load

The application port is separate from port 18400. Use a fixed demo port such as 18005 and forward it, or expose the application through an approved reverse proxy.

Restart creates a different instance ID

Restart terminates the old process and creates a new managed instance. Use the new instance row for subsequent demo runs, metrics, logs, and stop operations.

Clipboard actions fail

Use 127.0.0.1, localhost, or HTTPS. Browser security policy can deny clipboard writes from an insecure remote origin.

Repository boundary

• UI code, browser configuration, and the thin API/UI bridge belong in sage-opc-ui.
• Discovery, process management, app execution, metrics collection, reports, and API routes belong in sage-examples/opc.
• Application-specific dependencies and launch metadata belong with the corresponding application or its OPC manifest.