Skip to content
Python
14.6 KB
Raw Blame

OpenWorker management UI

A separate browser UI for OpenWorker Service. The UI server calls the same authenticated REST API as ows; it has no PostgreSQL, Kubernetes, model, or OpenShell credentials.

Start locally

Requires Node.js 20+ and a running OpenWorker Service from the same revision, including its listing and observability endpoints. There is no package install or frontend build step. Rebuild/redeploy the service from the same revision first if your existing image predates the listing endpoints; see service build instructions.

Save a configuration file (these are connection details, not credentials):

{
  "serviceUrl": "https://your-service.example.com",
  "serviceId": "your-service-id",
  "namespace": "your-namespace",
  "port": 58641
}

Use the service ID/namespace from your deployment configuration. For a local service, http://127.0.0.1:PORT is accepted. For a private CA, start Node with NODE_EXTRA_CA_CERTS=/path/to/ca.crt; do not disable TLS verification.

node harness/service-ui/server.mjs /path/to/ui.json

Open http://127.0.0.1:58641 and sign in with an existing service token. Issue scoped credentials with ows credentials issue as described in the Deployment options. There is no public bootstrap or default password. Use separate runner/publisher/administrator credentials as needed.

What is connected

  • Overview / Activity: real, scope-filtered session summaries and session counts by day. Charts describe only the loaded page; they are not global usage totals.
  • Observability: authorized run search, selected-page usage summaries, model/purpose and tool groups, and watermarked turn timelines. Missing usage stays unknown; scan/group limits remain visible. See below for counting and process-health scope.
  • Agents: visible immutable releases, definition inspection, publication, activation, and task submission. Release JSON selects tools already installed in the service. It cannot upload native binaries or arbitrary server launchers.
  • Sessions: paginated directory, filters, recorded messages/results, expandable event trace, SSE updates, sending turns, approvals/questions, and cancellation. Decisions carry the exact run/interaction and policy bindings shown to the user. Durable control receipts distinguish requested decisions from applied decisions and remain visible after a browser reload.
  • Infrastructure: real desired/observed worker capacity, revision-safe manual scaling, RuntimeProfile creation/activation, and administrator environment inspection.
  • Settings: revision-safe admission/compaction/limit configuration, expiring service-token issue/revoke, and bounded security audit inspection.

Controls are shown according to the signed-in role; the service reauthorizes every request and filters resource scope. Service administration does not grant tool approval or run authority. Publishing and activation remain separate capabilities.

Grafana/Langfuse are reserved UI locations, not newly implemented exporters. Provider credentials and endpoint enrollment remain deployment-managed. The UI is not an SSO implementation, a cloud-node autoscaler, or a replacement for OpenShell provisioning.

Browser and process boundary

Tokens are held only in UI-server memory. The browser receives an opaque HTTP-only, SameSite=Strict cookie and a CSRF token; service tokens are not saved in browser storage, URLs, configuration files, or logs. Login fields are cleared immediately. An explicitly issued new token is shown in its drawer for copying before issuance; it is cleared on close. Private browser mode is useful on shared machines.

Sessions expire after 30 minutes (configurable sessionSeconds, capped at one hour), or earlier when the service credential expires. Service revocation is checked on upstream requests and streams. Logout/expiry abort open upstream requests. Restarting the UI requires signing in again and does not cancel harness work.

The fixed upstream and service/namespace headers cannot be changed by the browser. Routes and query parameters are allowlisted. Host/Origin/Fetch-Metadata checks, CSRF checks on writes, response size limits, bounded sessions/concurrency, and a restrictive CSP protect the browser boundary. The service still rejects direct browser Origin requests. No generic forward proxy is exposed.

Writes are never retried automatically. A lost response retains the exact body and idempotency key for Retry same request. Do not refresh the page while resolving an uncertain write; copy the displayed idempotency key when investigating it. A changed configuration or scale revision must be re-read before a new update. No UI retry replays a tool action whose result is unknown.

Container

docker build -t openworker-service-ui:local harness/service-ui

For a container, add "host":"0.0.0.0", "port":8080, and an explicit publicOrigin to ui.json. Bind the published port to loopback for local testing:

docker run --rm --read-only --cap-drop=ALL \
  --security-opt=no-new-privileges \
  -p 127.0.0.1:58641:8080 \
  -v /absolute/config-directory:/config:ro \
  openworker-service-ui:local

The file inside the mount is /config/ui.json. For this local example set publicOrigin to http://127.0.0.1:58641. The container must be able to reach the configured service URL. allowInternalHttp: true is an explicit local-test option for e.g. http://host.docker.internal:PORT; production uses authenticated HTTPS to the service. Never mount an API administrator token into the UI container.

Kubernetes

The existing service chart has an optional managementUI Deployment and Service:

managementUI:
  enabled: true
  image: registry.example.com/openworker-ui@sha256:YOUR_VERIFIED_DIGEST
  publicOrigin: https://manage.example.com
  serviceUrl: https://ows-api.your-namespace.svc
  caSecret: service-api-ca # optional; ca.crt must trust the API certificate

The API certificate must match serviceUrl. Route your TLS ingress to the chart's <release>-ui Service, preserving the original Host and Origin headers and disabling SSE buffering. Restrict direct access to the UI pod to your trusted ingress. The UI uses secure __Host- cookies when publicOrigin is HTTPS; forwarded headers cannot override that configured origin. The chart requires HTTPS origins and digest-pinned images. No ServiceAccount token or execution/database Secret is mounted.

This version runs one UI replica with in-memory browser sessions and Recreate rollouts. APIs/workers can remain replicated independently. A UI rollout signs users out; durable harness work survives. Shared browser session storage or sticky-routing support is needed before scaling UI replicas. SSO remains a later addition.

Verification

node --test harness/service-ui/test/server.test.mjs harness/service-ui/test/observability.test.mjs
node --test deploy/service/chart.test.mjs

Real PostgreSQL/API/browser acceptance (use a disposable PostgreSQL instance):

export OW_PG_TEST_URL='postgres://...'
export OW_PROBE_RUNNER=/absolute/path/to/linux/openworker
export OW_PLAYWRIGHT_MODULE=/absolute/path/to/playwright-or-playwright-test
cargo test --manifest-path harness/Cargo.toml -p openworker-server-reference \
  --test management_ui -- --ignored --nocapture

Add OW_UI_CONTAINER_IMAGE=openworker-service-ui:local to run the same suite against the read-only Linux UI container on Docker Desktop (uses port 58643 and host.docker.internal). The test creates and removes its own database schema/UI container. Fixtures exercise real scoped reads, durable control admission, config, capacity requests, release/profile publication and credential lifecycle. They do not execute a model or apply tools; those worker/provider tests remain separate.

Design mock

The original sample-data mock is preserved for visual comparisons:

node harness/service-ui/preview.mjs

It opens on port 58640. The production UI lives in public/; the mock lives in mock/. Sample records and chart values are never used as a live-data fallback.

Complete-stack local Kubernetes qualification

deploy/service/qualify-ui-kubernetes.mjs drives a real browser against a UI pod, Rust API, PostgreSQL, service worker and NVIDIA OpenShell sandbox. It uses the scripted test model to exercise real tool effects without a model API key.

Use the dedicated kind installer from the M4 guide with a freshly built service image containing the UI listing endpoints, the management UI image, and the matching runner image imported by digest. Before installing the service, extend its local certificate to the API Service DNS name:

node deploy/service/kubernetes-local.mjs init .ow-service-ui /private/install.json
node deploy/service/ui-kubernetes-local.mjs prepare .ow-service-ui
node deploy/service/kubernetes-local.mjs install .ow-service-ui
node deploy/service/ui-kubernetes-local.mjs install .ow-service-ui UI_IMAGE_DIGEST
OW_PLAYWRIGHT_MODULE=/absolute/path/to/playwright-or-playwright-test \
  node deploy/service/qualify-ui-kubernetes.mjs .ow-service-ui

The helper installs a local TLS ingress and uses loopback port-forwards on 58444 (API) and 58644 (UI). Node verifies the generated CA; the test browser trusts only the generated leaf certificate's SPKI. Production TLS validation is unchanged. Namespaces must satisfy the existing dedicated kind installer's naming/ownership checks. There is no Red Hat OpenShift installation in this qualification.

The test publishes a profile/release through the UI, submits a task, approves each required tool call, restarts the API while approval is parked, restarts the UI during execution, and independently reads a persisted file to verify exactly one append. It also cancels an active command, scales to two ready workers, closes the session, and deletes its remote environment. A remote cancellation can correctly finish as interrupted with outcome_unknown; the test requires an applied cancel receipt, no tool replay, and durable unknown-outcome history rather than claiming rollback.

A failed run retains a journal and never starts the original task again automatically. Inspect its durable state first. The two explicit resume switches in the script only support their recorded, known checkpoints. After successful session/environment cleanup, use the existing guarded destroy command with the exact deployment ID:

node deploy/service/kubernetes-local.mjs destroy .ow-service-ui EXACT_DEPLOYMENT_ID

Then dispose of copied private input/token files. Keep only the sanitized report and screenshots needed for review. This fixture is local ARM64 kind/OpenShell qualification; AWS/GCP, x86-64, and Red Hat OpenShift require their own deployment evidence.

Observability

Open Observability for summaries of a recent page of up to 25 authorized runs. A run is one submitted turn, not an entire session. Page navigation replaces the selection; these charts are not unbounded deployment totals. Activity and Overview retain their existing operational session charts.

Find a run queries the service as you type (250 ms debounce). Results are paginated, with at most 100 matches retained in the picker; narrow the search for more. Arrow keys and Enter choose a result; Escape closes the picker. Stale search responses are discarded. No full run directory is downloaded. Selecting a run loads its timeline and summary at the same high-water cursor. Refresh explicitly to rebuild the view; there is no new background polling.

Usage includes reported tokens by purpose, model/tool call counts, accumulated work, exclusive phase duration, average first output from known model samples, and returned tool-result bytes. Missing values show —; a partial reported total says + unknown. Cache/reasoning counters are subsets. A truncated scan/group list shows Partial summary, with coverage/counting details available on expansion.

Timeline pages load 100 records at a time (at most 1,000 retained in the browser). The summary independently scans up to 4,096 records. Select a bar for timing, usage, outcome and metadata, or select a tool in the Usage table to filter its loaded timeline calls. Parallel spans retain their actual positions; absent duration is a marker, not a zero-length measured action. High-water cursors bound reads but do not freeze late commits or retention across requests.

Administrators can expand Recorder & exporter health for the serving API's process counters. These are not aggregated across workers/API replicas and do not prove database connectivity or lossless recording. Observer/runner credentials cannot retrieve those process-wide counters. Credentials, database URLs and exporter configuration are never returned by that endpoint.

Deploy API and UI from the same revision. Enable recording in the existing service configuration and run explicit migrations as described in the chart guide. If recording is disabled or unavailable, run search remains usable; no sample data or execution-database fallback replaces missing recording data. Observability guide.

Browser qualification

With an installed Playwright module/browser and Docker running, the existing owned-container qualification helper can also drive this UI against two disposable PostgreSQL databases and the real Rust API:

OW_OBSERVABILITY_UI_BROWSER=1 \
OW_PLAYWRIGHT_MODULE=/absolute/path/to/playwright-or-playwright-test \
OW_OBSERVABILITY_UI_OUTPUT="$PWD/.ow-service-observability-ui-screens" \
  node deploy/reference/qualify-observability.mjs .ow-service-observability-ui-test

The state directory must be new and gitignored. The output contains deterministic fixture screenshots and a sanitized UI report. No provider key is needed; no tools execute. Add OW_OBSERVABILITY_UI_IMAGE=sha256:YOUR_LOCAL_UI_IMAGE_ID to test the read-only Linux UI container instead of a host UI process. The image must already exist locally; the fixture never pulls it. The container test uses Docker Desktop's host.docker.internal to reach the temporary host API, with explicitly enabled local HTTP. Production TLS verification is unchanged. Only the test's exact labeled container and temporary connection-only configuration directory are removed.

The browser checks real scoped reads, separate recording storage, pagination, unknown/empty records, disabled recording and service-token revocation. Delayed searches and busy/transport/partial-coverage cases are injected at the browser boundary and identified separately in the report. Screens are reviewed at 1440 px and 390 px widths; no full Kubernetes rollout or cloud sizing is implied.