Skip to main content
Hosted Instructions visual proof lets an authorized employer or agent inspect the actual OpenTrain Instructions UI without running a local browser. OpenTrain captures the real employer workspace or a real designated test-worker reader in Chromium and returns private PNG, ARIA, diagnostics, and provenance artifacts.
Direct API, CLI, and MCP renders are for agents. They do not require a Vercel login or an interactive browser session. Human observe links are separate: they are short-lived and require normal OpenTrain authorization.
Agents should fetch the PNG and ARIA artifacts directly. Create an observe link only when an authorized human needs to inspect the same pinned render.

​
Workflow

  1. Read capabilities to discover audiences, targets, viewports, retention, and worker-coverage rules.
  2. Create a session pinned to the job’s current canonical Instructions tree.
  3. Select a page or stable node, or include it when creating the session.
  4. Render desktop, mobile, or both using the current state revision.
  5. Inspect the PNG and semantic evidence directly, or mint a human review link.
  6. Revoke the link or expire the session when review is complete.

​
Endpoints

​
Create and render

Employer session:
Worker session:
Worker proof is valid only through a real contract designated for testing. The response carries typed workerCoverage; no synthetic worker is substituted. Render with the session’s current revision:
The response binds each artifact to the exact session, audience, source tree, page/node, viewport, render revision, checksum, and byte size. It also reports source drift against the live canonical Instructions. A successful render sets browserRenderVerified: true. collaborationSyncVerified is always false. The capture proves what the renderer displayed at that revision; it cannot prove that an already-open collaborative browser received a real-time update.

​
Authorization and safety

  • Reads and artifact access require instructions:read.
  • Session control, rendering, and link mutations require instructions:write, an Idempotency-Key, employer job access, and the Instructions visual-proof rollout for the actor.
  • State-changing operations require the current expectedStateRevision and fail closed on drift.
  • Sessions, artifacts, and links are organization-bound, expiring, and revocable.
  • Visual proof writes only isolated preview evidence. It never changes an Instructions page or learner record.
  • Retry a transient renderer 503 with the same idempotency key.

​
SDK

@opentrain-ai/sdk 0.21.0 or later exposes getInstructionsVisualCapabilities, createInstructionsVisualSession, getInstructionsVisualSession, manageInstructionsVisualSession, renderInstructionsVisual, artifact list/get, and link create/list/revoke. Use the machine-readable OpenAPI document for complete request, response, and error schemas.