Viewer reference

The Viewer presents captured and live runs for one PtcRunner project. It is a local inspection surface, not a general remote administration service.

What it shows

The Runs tab lists the project's captured traces read-only. A run page shows turns, tool calls, effective prelude components, and called models attributed through the backend's validated terminal LLM reconciliation, including unmatched request starts. Incomplete or accounting-relevant dropped events are labelled as unavailable accounting. Configured but unused aliases do not appear as called models. Calls without attributable identity are not guessed into model identities. The separate model-label field is the manifest label fingerprint, not a record of which model served the run. When the project records artifacts.inspection and grants viewer.private, it also shows generated programs, prelude sources, and model exchanges. Each model response identifies its install alias and, when the adapter attested one, its configured resolved model. This configuration evidence is separate from the header’s accounting of observed calls.

When the project enables viewer.repl, a run page can open a bounded analysis REPL over an immutable capture of the selected run. The Live tab shows runs that report through PTC_VIEWER_URL; it can also launch the project's workflow or evaluate one expression in a declared mission's sandbox. The Live tab lists newest first.

Starting it

ptc viewer PROJECT.json [--port PORT] [--listen ADDRESS] [--env-file FILE]

--port overrides the project's viewer.port; when neither selects a fixed port, the default 0 asks the operating system for a free one. Startup prints the selected address. When an explicitly selected port is occupied, the command distinguishes another PTC Viewer, including its project path, from another service and reports the conflict. It runs in the foreground until Ctrl+C.

The Viewer never searches for .env. Environment-backed credentials come from the inherited environment, the project's host.env_file, or the exact file passed with --env-file FILE; that option overrides host.env_file for work launched from the Live tab. Each launch reads its own file snapshot and restores the declared variables on exit. The foreground Viewer command keeps the file path for launches and does not load it while serving. Host-configured file and literal credential bindings remain available.

The Viewer ships in the standalone release and container image. It is not part of the published Hex package, where ptc doctor reports the optional Viewer as unavailable.

The project reference documents the viewer block.

Exposing it

The Viewer binds to 127.0.0.1 by default. --listen 0.0.0.0 is the only alternative; it accepts connections through every network interface and prints a warning. Every route, including static assets and Live ingestion, requires an HTTP authority of localhost, 127.0.0.1, or [::1] with the actual listener port. Other hosts and ports receive 403 forbidden_request, even with a valid Live token. Port forwards must preserve the listener port. Browser mutations require an HTTP Origin matching that same authority. Set a fresh PTC_VIEWER_TOKEN of at least 32 bytes before allowing any non-loopback peer; for example, generate one with openssl rand -hex 32.

For a browser arriving through a non-loopback peer, keep the page authority at localhost, 127.0.0.1, or ::1 through a port forward, then open the Viewer once with ?live_token=THE_TOKEN to bootstrap Live access. The page removes that query parameter after use. Query tokens are accepted only for the entry page and live event stream: the native EventSource client still needs URL authentication because it cannot set an Authorization header. Other Live requests use Bearer headers, and query tokens never authorize mutations. The initial URL and stream URL can expose the token in browser history or request logs; keep those private and rotate the token after exposure. The token protects Live ingestion and controls; it never authenticates the Runs trace browser, so exposing the Viewer can disclose trace and private inspection data.

For container binding and host-port rules, see Docker installation.

Reporting a run

Set PTC_VIEWER_URL for ptc run to report progress to the Live tab. When the Viewer requires a token, set the same PTC_VIEWER_TOKEN for the run. A token is sent only over HTTPS or HTTP to localhost, IPv4 loopback (127.0.0.0/8), or IPv6 loopback (::1). URLs must have a host and no userinfo, query, or fragment. Redirects are refused. Invalid or insecure targets fail delivery. Reporting is best-effort and never changes the run result. It sends the exact manifest label, or the manifest filename when no label exists, and workflow entry to the Viewer for display; trace metadata keeps its fingerprinted label.