[promptless]

Open in Promptless

Coordination: #1047 (Cursor trace collection) has merged to main as a571437. This branch now includes that merge, so this PR can merge on its own.

Proposed changes

Cloud agents such as Claude Tag run in sandboxes where no one can approve host enrollment in a browser. An organization admin creates a cloud integration grant on Settings → Cloud integrations. Each cloud execution then uses the grant to enroll itself and upload its native Claude Code or Codex traces to the customer's analyzer. Cloud enrollment first shipped in stable PIG 0.3.5 (schema revision 5) and works the same way in the current stable release, 0.3.6.

• New page: governance/get-started/capture-cloud-agent-traces.mdx. Covers:
  • prerequisites, including PIG 0.3.5 or later
  • creating a grant and saving its one-time plicg_ token
  • giving the token to Claude Tag (a Bearer custom connector, proxy transport) or to another runner (PROMPTLESS_CLOUD_GRANT or PROMPTLESS_CLOUD_GRANT_FILE)
  • building the collector with pig cloud-bundle for Claude Code, or running it directly for Codex
  • verifying capture, how executions enroll, finding cloud traces, revoking a grant, and troubleshooting by status code
• Reachability. Any runner needs an HTTPS address it can reach from its sandbox, with no redirects. Only Claude Tag needs a public endpoint, because its Agent Proxy blocks private IP ranges. The same scoping is applied in plan-your-deployment.mdx, deploy-the-analyzer-worker.mdx, networking-and-identity.mdx, and deploy-on-aws.mdx.
• pig-cli-reference.mdx. Adds pig cloud-bundle and its options.
• enroll-your-hosts.mdx and supported-agents.mdx. Point cloud sandboxes to the new page. docs: Document Cursor native trace collection for PIG (analyzer 0.3.3+) #1047's Cursor guidance is preserved.
• Removed: the "Enrollment fails before approval opens" host-enrollment row. It concerned plugins built before the dashboard route rename, which isn't cloud-capture scope, and docs: Complete the PIG 0.3.6 installation path, from release verification to a verified first session #1039 had already dropped it.

The /pig/... dashboard route updates already landed in #1039, so this PR no longer carries them.

Released capability compared with Claude Tag acceptance

Cloud enrollment is released: the routes, grants, dashboard page, and collector are on stable 0.3.5 and later, with no feature flag. Claude Tag has not completed a live end-to-end acceptance run. A Tag experiment showed that Tag adds Authorization when the collector leaves it out. It has not been confirmed that Tag passes X-Promptless-Producer-Token through to the analyzer. The page asks readers to confirm that before relying on Tag, which matches the dashboard's own notice. It makes no claim of a live Tag end-to-end success.

Source evidence

• pig-deploy stable catalog. Lists 0.3.1, 0.3.3, 0.3.4, 0.3.5, and 0.3.6, with 0.3.6 as Latest. The 0.3.5 and 0.3.6 manifests have schemaTo: 5, and their release notes say schema revision 5 is for cloud host enrollment.
• Analyzer images. 0.3.5 was built from Promptless/promptless 63e64e85, and 0.3.6 from 625624a7. Both contain the cloud routes from Promptless/promptless#5441. 0.3.4 predates them.
• pig-deploy v0.3.6 bootstrap Ingress. Routes exactly /healthz, /v0/host-enrollment/policy, /v0/host-enrollment/check-ins, /v0/cloud-enrollment/leases, and /v0/traces/batches.
• Analyzer 625624a7.
  • Exactly one Authorization: Bearer header. The plicg_ grant token is required on enrollment.
  • On policy and upload calls, exactly one X-Promptless-Producer-Token (plicl_) plus a target query parameter.
  • Both credentials are checked with Promptless on every policy and upload request.
  • Status codes: 401 for missing, duplicate, or invalid credentials. 403 for a grant that is expired, revoked, used up, out of scope, or blocked by policy. 409 for an execution identity that conflicts, was copied, or was revoked. 503 when Promptless or the policy is unavailable.
• Promptless/promptless main 934ae08.
  • Cloud integrations page and trace-feed filters.
  • Grant limits: name 1–100 characters, provider ^[a-z][a-z0-9_]{0,63}$, lease 60–3,600 s, execution limit 1–100,000, expiry within 365 days.
  • Revocation is permanent and applies on the next request.
  • The dashboard offers only Claude Code and Codex.
• pig-toolchain main 4c02abf.
  • pig cloud-bundle options. --worker-url must be an HTTPS origin.
  • The five plugin hooks, the bundled cloud-capture.json, and the transport rules. Proxy mode fails if a grant variable is set.
  • status.json states, including blocked with bootstrap_upgrade_required when the host enrollment policy requires a newer collector.
  • pig-toolchain has no versioned releases; users install it from main.
• Claude Tag docs (Add connectors). "Private IP ranges and cloud metadata endpoints stay blocked regardless."

Checklist

• Instructions and examples match the current product behavior.
• Links and image references are valid.
• Changed pages render correctly.

Merge resolution: f9152d9 merges main at a571437 into this branch. The only conflicts were in enroll-your-hosts.mdx and supported-agents.mdx. Both were resolved by keeping this branch's content, which already contained #1047's final head 525383f. main at a571437 has the same tree as 525383f, so the resolved tree is the same as the reviewed 753ce83. On f9152d9, remark --frail and Vale report no findings on the eight changed files, and docmeta validate passes. Earlier validation on the combined head: npm run lint:md (remark --frail) and docmeta validate pass. Vale (collection config plus Promptless and KB rules) reports no findings on any changed MDX file. npm run build passes. A local linkchecker crawl of the new page and its links found no broken links; the only errors were dev-server-only routes such as /sitemap-index.xml and /llms.txt. The external Claude Tag and pig-deploy links return 200, and the #restrict-by-path-or-method anchor exists.

Trigger Events

• Promptless/promptless#5441: Cloud agent enrollment and capture
• Promptless MCP by Adit Chandra

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
promptless-docs	Ready	Preview	Oct 16, 2026 9:06pm UTC