Files

InspectionBuddy

A second set of eyes for the assembly line.

A sample application built with the OpenWorker Harness SDK. Photograph a part, review the AI’s visible findings and suggested checks, ask follow-up questions, and record the inspector’s decision. Six synthetic photos let you try damaged and healthy-looking parts without supplying your own images.

The app is called InspectionBuddy; its source lives in harness/examples/expertbuddy/. It demonstrates two ways to use the same SDK:

Try it Where the agent runs What you need
Local development Managed Rust harness process alongside the Node app Node.js 20.19.5+ and an OpenAI key. No Docker or Kubernetes.
Edge deployment OpenWorker service on a separate server An existing service, scoped credentials and persistent app storage.

Try it locally — no cluster

From the repository root:

cd harness/examples/expertbuddy
npm ci
cp .env.example .env

Edit .env to supply OPENAI_API_KEY and a vision-capable OW_MODEL that your account can use. The SDK installs its matching native runtime automatically; no Rust compilation is required. Keep optional npm dependencies enabled for this mode. Then:

npm start

Open localhost:4336. Select a sample or upload a PNG, JPEG or WebP under 8 MB, add inspection context, and select Assess this photo. Review the annotations, open Agent activity for progress and token usage, ask a follow-up, and Record your decision. Find saved work in Inspection log.

Browser on this computer
        │ localhost:4336
        ▼
Node app ─────────────── .data/ photos + inspection records
        │ SDK over private stdio
        ▼
Managed Rust harness ── .data/harness/ sessions + SQLite traces
        │ HTTPS
        ▼
OpenAI vision API

This mode uses a real model and a tool-free agent. sandbox: "off" is appropriate here because it registers no filesystem, shell or other tools. The Node app saves photos; the model receives immutable image and reference-guide attachments. The browser never receives the model key. Photos and context are sent to the cloud model; this example does not implement offline inference.

npm start reads .env; process environment variables take precedence. PORT changes the browser port, and DATA_DIR changes the persistent data directory. Use a distinct DATA_DIR for each local harness or remote service; saved session references belong to that backend and are not migrated when you switch modes. Local mode binds to loopback and rejects cross-origin requests. It is a development entry point, not a public multi-user service. Keep one app process per data directory. Keep the same model and agent definition when reopening existing state; use a new OW_AGENT name or a fresh DATA_DIR after changing the immutable definition.

Why deploy the agent at the edge?

A factory may have several inspection workstations and cameras but one site-local server. Centralizing agent sessions and inspection records there lets operators close a browser, switch workstations or reconnect without moving the agent loop onto each device. The interface remains lightweight; execution and storage stay with the site’s infrastructure. A configured cloud model provides vision inference in this sample; moving orchestration to the edge does not make inference local.

               FACTORY / SITE NETWORK
┌──────────────────────┐       ┌────────────────────────────────────┐
│ Inspection stations  │ HTTPS │ Edge server                        │
│ Browser + UI proxy   ├──────► │ InspectionBuddy application API    │
│ Camera / photo input │       │   ├─ photos + inspection records   │
└──────────────────────┘       │   └─ Harness.connect()             │
                               │            │ HTTPS + scoped token │
                               │ OpenWorker service                 │
                               │   API / controller / agent workers │
                               │   ├─ PostgreSQL sessions + traces  │
                               │   └─ OpenShell → tool sandbox      │
                               └────────────────┬───────────────────┘
                                                │ HTTPS; worker-held key
                                                ▼
                                      Configured vision provider

The workstation talks to your application API, not directly to the harness or provider. The app holds an owned-scope operator credential; only trusted harness workers receive model keys. Service administrators register the agent and RuntimeProfile separately. The production topology supports several stations; the sample itself uses one shared app credential and a single-writer file store. Add organization login, user authorization and shared storage before wider rollout.

Connect the workstation to an edge application

Create a separate, ignored .env for the workstation:

INSPECTIONBUDDY_MODE=frontend
PORT=4336
EDGE_API_URL=https://inspection-api.example.com
EDGE_APP_TOKEN_FILE=/absolute/private/app-token

Run npm ci --omit=optional and npm start. The workstation needs only the application token. It does not need a model key, harness operator token, native harness binary or Kubernetes access. A loopback SSH tunnel is also supported with EDGE_API_URL=http://127.0.0.1:18447; non-loopback upstreams require HTTPS. For a private service CA, set NODE_EXTRA_CA_CERTS before starting Node.

See edge setup and deployment for service registration, app configuration, secret placement and the Kubernetes application manifest.

Can I run an OpenWorker service locally without Kubernetes?

The local Docker service playbook runs the OpenWorker API, controller, workers and PostgreSQL in Docker Compose. It still requires a reachable OpenShell gateway backed by Kubernetes, plus matching runner artifacts. It is useful if you already operate that gateway elsewhere, but it is not a standalone Kubernetes-free service installation.

For a completely cluster-free InspectionBuddy test, use local development above. It exercises the published SDK, real attachments, sessions, progress and usage through a managed harness process. It does not test service authorization, RuntimeProfile provisioning, worker failover or Kubernetes/OpenShell isolation. Use the private Kubernetes guide when you want to qualify those service boundaries.

What the example demonstrates

  • Image and UTF-8 reference attachments, followed by questions in the same session.
  • Streamed journal activity and aggregate model tokens across the assessment and follow-ups.
  • Schema-validated findings and bounded image annotations; model output is rendered as text.
  • Durable photos, reports, inspector decisions and separate agent session references.
  • Recovery of saved runs without blindly replaying uncertain requests.

App records use atomic file replacement and a single writer. Run one replica with a persistent volume and a Recreate strategy. Harness session and trace storage is separate: SQLite locally, PostgreSQL in the service deployment. Usage may be unavailable or partial when recording is disabled or a provider omits counts.

AI observations never automatically approve a part. The synthetic images and demo reference guides are illustrative, not production acceptance criteria. A photo cannot establish hidden weld integrity, electrical continuity or calibrated dimensions. An inspector records the final disposition. Image provenance: asset hashes and generation prompts.

Tests and source map

npm test
# Explicit opt-in: calls the running app and incurs real model usage.
# Set INSPECTIONBUDDY_URL if the app is not on localhost:4336.
npm run test:live

The automated suite covers input/report validation, annotation bounds, durable records, idempotency, authorization, cross-origin writes, human-only decisions, usage accounting and recovery. Deterministic test adapters are confined to tests. The live check submits a healthy-looking panel and a defective weld and verifies saved reports, photo retrieval and nonzero recorded model usage.

File Responsibility
server/local-agent.mjs Local Harness.start(), tool-free agent and persistent traces.
server/agent.mjs Edge Harness.connect(), attachments, streaming, recovery and usage.
server/engine.mjs Inspection lifecycle, progress and follow-ups.
server/store.mjs Photos, records and inspector decisions.
server/index.mjs Local app, authenticated edge API or workstation proxy.
public/app.js Inspection UI, annotations, history and decisions.

This is repository example source, not part of the SDK/runtime npm packages.