Enroll your hosts

Once a host installs your Claude or Codex plugins, the injected host runtime (promptless-host-runtime) is present. It is ready to enroll with your worker and collect that host’s session traces.

Point the host at your worker

The host runtime reads the worker base URL from the PROMPTLESS_WORKER_BASE_URL environment variable. A self-hosted deployment must set PROMPTLESS_WORKER_BASE_URL on each host to your own worker’s hostname before you enroll that host. That is the hostname you expose in Deploy the analyzer worker. The compiled-in default points at Promptless’s own hosted worker, so it is not a general-purpose fallback for a self-hosted deployment.

The browser approval step runs through the Promptless dashboard at https://app.gopromptless.ai, which is separate from the worker endpoint. Approval authorizes the host; the host learns where the worker is from PROMPTLESS_WORKER_BASE_URL.

Enroll a host

Enrollment uses a browser approval, so a signed-in member of your Promptless organization authorizes each host. Any signed-in member can approve a host (org-admin is not required). The approval is attributed to the approving user, recorded server-side as who approved that host.

1. Run enroll on the host, naming the host family with --host.

   promptless-host-runtime enroll --host claude

   Use --host codex or --host claude-desktop for those families.

2. Approve in the browser. The runtime opens the enrollment page and listens on a 127.0.0.1 loopback callback. A signed-in organization member approves the host there.

3. Let the runtime cache the credential. After approval, the runtime polls for the one-time per-host credential (a plihost_ token) and caches it locally.

Note

The per-host credential is returned in plaintext exactly once and stored owner-only on the host. For how it is verified, see Trust and data model.

How collection runs

After enrollment, collection runs on its own through generated lifecycle hooks. You do not schedule it:

• On SessionStart, the Codex and Claude Code hooks ensure the host configuration and run a quiet collection pass. The Claude Code hook also runs a best-effort pass for --host claude-desktop.
• On terminal events (Stop, SessionEnd, and SubagentStop where supported), the hooks run collection only.

Every collection pass runs detached and non-blocking, so a worker, policy, or upload problem never interrupts the agent session. Collection uploads only new byte ranges past the local ledger watermark. For what those uploads contain and how sessions are reconstructed, see Trace object and sources.

Check status or reset

To inspect a host’s enrollment and configuration, run:

promptless-host-runtime status

To clear a host’s local enrollment state (for example, before re-enrolling), run:

promptless-host-runtime reset