Enroll your hosts
Overview
Section titled “Overview”Host enrollment connects a person’s agent installation to your trace analyzer. Instructions work without enrollment. Enable collection when you want PIG to analyze how those instructions perform in real sessions.
This guide continues the Acme example. It covers Claude Code, Codex, and Cursor, and the Claude collector can also discover Claude Desktop traces on the same machine. Gemini plugins don’t collect native traces. For agents that run in cloud sandboxes, such as Claude Tag, see Capture traces from cloud agents.
1. Authorize the host
2. Upload to your analyzer
Before you start
Section titled “Before you start”You need:
- An installed analyzer that passes its HTTPS checks from the host’s network. For Cursor, the analyzer must run release 0.3.3 or later.
- The analyzer’s HTTPS address, without a path. Your operator provides it and confirms the analyzer’s organization. This guide uses
https://traces.acme.example. - A published hub, with the
pigplugin installed on the host. - Python 3.9 or later on the host. The generated launchers for Claude and Cursor also need Node.js, and the generated Codex hooks need a POSIX shell.
- Network access from the host to the analyzer address and to the Promptless enrollment service.
- A signed-in Promptless organization member to approve enrollment.
Enable collection and enroll a host
Section titled “Enable collection and enroll a host”To hand these steps to a coding agent on the pilot host, copy this prompt. You still approve the host in your browser. Set up PIG with a coding agent covers the whole setup.
Enable PIG trace collection for our Instruction Hub and enroll this host.Follow https://promptless.ai/docs/governance/get-started/enroll-your-hosts.mdand phase 6 of https://promptless.ai/docs/governance/agent-setup-guide.md
Collection is approved for this host only.Inputs (discover these before you ask me):- Hub repository: [hub repository URL or local path]- Analyzer address: [for example, https://traces.acme.example]- Host family: [the --host value from the guide, for example codex or claude]
Show me the hub.yaml diff and wait for my approval before you publish it.Tell me when to approve the host in my browser. Report the runtime statusand anything still blocked.-
Enable collection in the hub
In
hub.yaml, change the existing setting:hub.yaml trace_ingestion:enabled: trueRun
pig verify, commit the change, and publish it through your hub’s CI. Then update the installed plugins on your pilot host.The compiler adds the host runtime and collection hooks only to the
pigplugin for Claude, Codex, and Cursor. Other plugins, such asdocsanddev, don’t receive them. The setting doesn’t provision an analyzer. When the setting is omitted orfalse, the build includes no runtime files or collection hooks.For Cursor, confirm that the Workers settings page shows Cursor ingestion supported for your analyzer. Analyzer releases 0.3.3 and later report Cursor support when they check in, and the default enrollment policy then includes Cursor. If a later check-in stops reporting support, the policy drops Cursor again.
-
Set the analyzer address
Before the first session with collection enabled, set this variable in the environment that launches the agent:
Terminal window export PROMPTLESS_WORKER_BASE_URL="https://traces.acme.example"For a terminal agent, launch it from that shell. For a desktop agent, set the variable through your organization’s desktop environment configuration, then restart the application. A variable exported in a separate terminal may not reach an application that is already running.
The runtime has a built-in Promptless worker address. Without this variable, the host doesn’t use your analyzer.
-
Approve the host
Start a new Claude Code, Codex, or Cursor session. The generated startup hook initializes the local runtime and starts enrollment when needed. In the browser, sign in to the correct Promptless organization and approve the host. Any signed-in organization member can approve, including members who aren’t administrators.
The approval page is at
https://app.gopromptless.ai/pig/enroll, separate from the analyzer URL. The runtime uses a local127.0.0.1callback during approval and retrieves a one-time host credential afterward. Enrollment records the approving user.If you need to start enrollment manually, find the installed
pigplugin directory in your agent’s plugin installation details and substitute its absolute path:Terminal window PIG_PLUGIN_ROOT="/absolute/path/to/installed/pig"python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" enroll --host codexUse
--host claudefor Claude Code,--host cursorfor Cursor, or--host claude-desktopfor Claude Desktop. The runtime is bundled inside the plugin, so run it from the plugin directory. If theruntimedirectory is missing, check that you published and installed the release with trace ingestion enabled.The command opens the approval page in the host’s browser. If it prints
"status": "setup_pending", approve the host in the browser and run the same command again. The host must be able to open a local browser and receive the127.0.0.1callback. Approval links expire after 15 minutes.The host stores its
plihost_credential locally with owner-only access. This credential is separate from the analyzer’s deployment credential. Do not copy host credentials between machines or into your hub. -
Verify collection and analysis
After manual enrollment, start a new session so the startup hook fetches the host’s configuration. To run that initialization yourself and check the result:
Terminal window python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" ensure --host codexpython3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" status --host codexstatusreports local enrollment state only. Use the same host family as in enrollment.Run a small, non-sensitive task in a repository selected for analysis, then finish the session. To confirm the upload from the host, run a collection in the foreground:
Terminal window python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" collect --host codex --include-activeIt prints
"status": "trace_upload_complete"with a nonzerobatch_countwhen the analyzer acknowledged the session’s data.trace_upload_partialmeans some data remains for a later retry. The operator should then verify all three outcomes:- Enrollment. The analyzer recognizes the host and accepts its check-in.
- Stored trace. The native session has reached the analyzer and its raw data is stored in the configured trace bucket.
- Completed analysis. After the configured quiet period, the session has a completed analysis run for the expected repository.
A completed run can produce no findings, and that is a valid result. Pod readiness, enrollment, and an upload acknowledgment alone don’t show that analysis completed. Use the operator’s deployment verification steps to inspect the server-side result.
How collection continues
Section titled “How collection continues”Generated hooks run collection in the background at session startup and at supported terminal events, with no scheduled task. Claude Code also attempts to collect Claude Desktop traces it can discover locally. Installing a plugin only in another application doesn’t create a separate Claude Desktop collection schedule.
The runtime tracks source progress locally and uploads incremental trace data. A connectivity problem can delay collection without interrupting the agent task. Keep the native session files and runtime state intact while troubleshooting so the collector can retry. See Trace object and sources for source details.
Cursor collection
Section titled “Cursor collection”With trace collection enabled, the Cursor pig plugin registers four lifecycle hooks: sessionStart, stop, sessionEnd, and subagentStop. Each hook has a 250 ms timeout and starts a background collector. The collector reads Cursor’s saved conversation data from its local session database in read-only mode. To avoid delaying Cursor’s own writes, it skips a database that does not use SQLite’s write-ahead log (WAL) mode.
The collector covers Agent sessions and subagents in the Cursor desktop app. It does not collect from the Cursor CLI, Cloud Agents, or Tab completions, and it does not export binary images. If the analyzer or enrollment fails, Cursor keeps working, and a later hook retries the pending collection.
Cursor’s hooks run the launcher with the PATH the Cursor app sees, so Node.js and Python must be on that PATH. The launcher looks for python3 or python, and on Windows for py -3 first. If it cannot find Python 3.9 or later, it records the problem in ~/.promptless/instruction-hub/cursor-launcher-status.json.
To enroll or collect manually, first set CURSOR_PLUGIN_ROOT to the installed plugin directory. The runtime reads the installed release from it. Then run the commands in steps 3 and 4 with --host cursor:
export CURSOR_PLUGIN_ROOT="$PIG_PLUGIN_ROOT"python3 "$CURSOR_PLUGIN_ROOT/runtime/promptless-host-runtime" collect --host cursor --include-activeOn Windows, set $env:CURSOR_PLUGIN_ROOT in PowerShell and run the runtime with py -3 in place of python3.
The adapter’s data format was checked against Cursor desktop 3.19.19, and synthetic tests cover the collector and analyzer contracts. End-to-end capture from the Cursor desktop app on macOS, Linux, and Windows has not yet been qualified. Enroll one pilot host per operating system and confirm a stored trace and a completed analysis for it before you enable Cursor collection more widely.
Troubleshooting
Section titled “Troubleshooting”| Symptom | What to check |
|---|---|
| Nothing happens at session startup | Confirm the enabled release of pig is installed, hooks are allowed, and Python is available; Claude’s launcher also needs Node.js |
| The wrong deployment appears during approval | Set PROMPTLESS_WORKER_BASE_URL in the agent’s process environment and restart it before retrying |
| The browser cannot finish approval | Sign in to the correct organization; check access to Promptless, the analyzer, and the local loopback callback |
| Host is enrolled but no trace appears | Complete a supported native session, run collect --include-active, and check its status, the diagnostics log, the collection policy, and access to the analyzer |
| A Cursor host is enrolled but no trace appears | Confirm the Workers settings page shows Cursor ingestion supported, Node.js and Python are on the PATH Cursor sees, and cursor-launcher-status.json reports no missing Python |
| Trace is stored but analysis does not complete | Ask the operator to check the selected instruction repositories, quiet-period eligibility, model configuration, and the analysis queue |
| A collected repository is not analyzed | The current analyzer binds GitHub repositories by repository ID; GitLab publishing support does not imply GitLab analysis support |
Local diagnostics are stored under ~/.promptless/instruction-hub/, including last-bootstrap-status.json and host-runtime-diagnostics.jsonl. Review them for the failed stage before sharing a redacted excerpt with your operator. Enrollment state contains credentials and should not be pasted into a ticket.
To clear local enrollment for one host family before approving it again:
python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" reset --host codex --yesReset is a troubleshooting action. It doesn’t remove server-side traces or revoke the host for your organization.
Stop or expand collection
Section titled “Stop or expand collection”To remove generated collection hooks, set trace_ingestion.enabled: false, publish, and update the installed plugins on affected hosts. Hosts still running an older enabled release keep its hooks until they update. This configuration change doesn’t delete existing traces.
After the pilot meets all three verification outcomes, enroll the next agreed group of hosts.
See also
Section titled “See also”- Understand findings, to turn analysis into reviewed instruction improvements
- Verify your deployment, for the operator’s server-side checks
- Trace object and sources, for how each native source is read and uploaded
- Capture traces from cloud agents, for agents that run in cloud sandboxes