Skip to content

For the complete documentation index, see llms.txt.

Enroll your hosts

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

Host runtimeStart enrollment from the installed plugin
Enrollment requestthen
Promptless enrollmentAn organization member approves in the browser
Host credentialthen
Host runtimeRetrieve and store the credential locally

2. Upload to your analyzer

Host trace collectorAuthenticate with the host credential
Session tracesthen
Trace analyzerReceive uploads at your HTTPS endpoint
Promptless authorizes enrollment. The host sends session traces directly to your analyzer using its own host credential.

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 pig plugin 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.

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.

Ask your agent: enable collection and enroll this host
Enable PIG trace collection for our Instruction Hub and enroll this host.
Follow https://promptless.ai/docs/governance/get-started/enroll-your-hosts.md
and 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 status
and anything still blocked.
  1. Enable collection in the hub

    In hub.yaml, change the existing setting:

    hub.yaml
    trace_ingestion:
    enabled: true

    Run 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 pig plugin for Claude, Codex, and Cursor. Other plugins, such as docs and dev, don’t receive them. The setting doesn’t provision an analyzer. When the setting is omitted or false, 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.

  2. 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.

  3. 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 local 127.0.0.1 callback 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 pig plugin 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 codex

    Use --host claude for Claude Code, --host cursor for Cursor, or --host claude-desktop for Claude Desktop. The runtime is bundled inside the plugin, so run it from the plugin directory. If the runtime directory 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 the 127.0.0.1 callback. 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.

  4. 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 codex
    python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" status --host codex

    status reports 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-active

    It prints "status": "trace_upload_complete" with a nonzero batch_count when the analyzer acknowledged the session’s data. trace_upload_partial means some data remains for a later retry. The operator should then verify all three outcomes:

    1. Enrollment. The analyzer recognizes the host and accepts its check-in.
    2. Stored trace. The native session has reached the analyzer and its raw data is stored in the configured trace bucket.
    3. 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.

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.

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:

Terminal window
export CURSOR_PLUGIN_ROOT="$PIG_PLUGIN_ROOT"
python3 "$CURSOR_PLUGIN_ROOT/runtime/promptless-host-runtime" collect --host cursor --include-active

On 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.

SymptomWhat to check
Nothing happens at session startupConfirm 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 approvalSet PROMPTLESS_WORKER_BASE_URL in the agent’s process environment and restart it before retrying
The browser cannot finish approvalSign in to the correct organization; check access to Promptless, the analyzer, and the local loopback callback
Host is enrolled but no trace appearsComplete 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 appearsConfirm 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 completeAsk the operator to check the selected instruction repositories, quiet-period eligibility, model configuration, and the analysis queue
A collected repository is not analyzedThe 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:

Terminal window
python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" reset --host codex --yes

Reset is a troubleshooting action. It doesn’t remove server-side traces or revoke the host for your organization.

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.