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 and Codex; the Claude collector can also discover Claude Desktop traces on the same machine. Cursor and Gemini plugins do not currently collect native traces.

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.

Before you start

You need an available analyzer, a published hub, and the installed pig plugin. Install Python 3.9 or later on the host. A signed-in Promptless organization member must approve enrollment. Claude’s generated launcher also needs Node.js. Codex’s generated hooks use a POSIX shell.

Your operator should provide the analyzer’s HTTPS address and confirm its organization identity. For Acme, this guide uses https://traces.acme.example. The host must reach that address and the Promptless enrollment service.

Note

Trace collection can include prompts, responses, tool calls, and code or documents present in sessions. On first discovery, the collector can upload existing session history, not just sessions started after enrollment. Review the data boundaries and agree on the pilot hosts and repositories before enabling collection.

To hand enrollment 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

   Change the existing setting in hub.yaml:

   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 to the literal pig plugin for Claude and Codex. It does not add them to docs or dev, and it does not provision an analyzer. With the setting omitted or false, generated runtime files and collection hooks are absent.

2. Set the analyzer address

   Set this environment variable in the environment that actually launches the agent:

   export PROMPTLESS_WORKER_BASE_URL="https://traces.acme.example"

   For a terminal agent, launch it from that shell. For a desktop agent, use your organization’s desktop environment configuration and restart the application. A variable exported in a separate terminal may not reach an already running GUI application.

   Do this before the first session with collection enabled. The runtime has a compiled-in Promptless worker default; a customer deployment must explicitly point hosts at its own analyzer.

3. Approve the host

   Start a new Claude Code or Codex 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; organization administrator access is not required.

   The approval page is hosted at https://app.gopromptless.ai/instruction-hub/enroll. It is 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:

   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 or --host claude-desktop for Claude Desktop. The runtime is bundled inside the plugin; it is not installed as a global promptless-host-runtime terminal command. If the runtime directory is missing, check that you published and installed the release with trace ingestion enabled.

   To enroll a machine you reach over SSH, or another host without a local browser, add --device to the manual enrollment command:

   python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" enroll --host codex --device

   The command prints an approval link. Open the link on a device that has a browser, such as your laptop, and approve the host there. The host needs no local browser, inbound port, or loopback callback.

   The command waits about 35 seconds for approval. If it prints "status": "setup_pending", approve the link and run the same command again. Each run resumes the same approval until it expires 15 minutes after the command first printed the link. After that, the next run prints a new link.

   The host stores its plihost_ credential locally with owner-only access. It is different 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 to let the startup hook fetch the host’s configuration. You can also request that initialization explicitly:

   python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" ensure --host codex
   python3 "$PIG_PLUGIN_ROOT/runtime/promptless-host-runtime" status --host codex

   Use the same host family as in enrollment. Run a small, non-sensitive task in a repository configured for analysis, then finish the session. The operator should 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. That is a valid result; pod readiness, enrollment, and an upload acknowledgment alone are not evidence that analysis completed. Use the operator’s deployment verification steps to inspect the server-side result.

How collection continues

Generated hooks run collection in the background during session startup and supported terminal events. They do not require a scheduled task. Claude Code also attempts to collect Claude Desktop traces it can discover locally. Installing a plugin only in another application does not create a standalone 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.

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
The host has no local browser	Run enroll with --device and open the printed approval link on another device
Device enrollment reports too many requests	Wait before retrying; approve or let pending approvals expire, since each pending approval counts toward a per-deployment limit
Host is enrolled but no trace appears	Complete a supported native session; inspect runtime diagnostics and check the host’s collection policy and network access
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 --yes

Reset is a troubleshooting action. It does not remove server-side traces or implement organization-wide revocation.

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 retain its hooks until updated. Existing traces are not deleted by this configuration change.

After the pilot meets all three verification outcomes, enroll the next agreed group of hosts. Continue to findings and remediation to turn analysis into reviewed instruction improvements.