Enroll your hosts

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

Enroll a host

Enrollment uses a browser approval so a signed-in member of your organization authorizes each host.

Run enroll on the host, naming the host family with --host:
Terminal window
```
promptless-host-runtime enroll --host claude
```
Use --host codex or --host claude-desktop for those families.
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.
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.

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