Trust and data model
PIG stores raw traces and canonical trace objects in your infrastructure. Analysis sends session-derived input to the model provider you configure. Promptless receives trace status and findings, whose text can describe details from a session.
Use this page to decide which hosts to enroll, where to run analysis, and who should have access to the resulting data. The architecture overview shows how the components connect.
Use cases
Section titled “Use cases”- Your security team reviews PIG before any host uploads a session. Where data goes lists each kind of data and the system that receives it.
- You choose pilot hosts and repositories. Transcripts can contain prompts, tool output, and file excerpts, so start with hosts whose work your organization approves for storage and analysis.
- You decide who can read findings. Findings and their GitHub issues can describe session details, so match repository access to that audience.
- You plan secrets for the deployment. Credentials and access lists each credential, what uses it, and what it grants.
Where data goes
Section titled “Where data goes”| Data | Destination | Purpose |
|---|---|---|
| Instruction assets and plugin definitions | Your Git repository and CI | Review and publish shared instructions |
| Compiled plugins | Installed agent hosts | Make instructions available during agent work |
| Native transcript records | Your analyzer and trace bucket | Preserve the source evidence for analysis |
| Canonical traces and optional context snapshots | Your customer-owned storage | Reconstruct sessions and the context available to an agent |
| Host attribution, ingestion progress, and analysis state | Your PostgreSQL database | Track uploads and coordinate processing |
| Session and instruction context | Your configured model provider | Analyze behavior and prepare proposed improvements |
| Trace identity, counts, and processing status | Promptless | Show collection and analysis progress |
| Findings, evidence summaries, and remediation state | Promptless and connected GitHub issues or pull requests | Explain problems and review proposed changes |
| Configured operational telemetry | Your selected observability systems | Diagnose deployment and analysis failures |
A native transcript can contain prompts, tool arguments and outputs, file excerpts, and other content the agent records. Treat it according to the sensitivity of the work your agents perform. The collector uploads native records as the agent wrote them and doesn’t remove secrets from transcripts before upload.
From hosts to your analyzer
Section titled “From hosts to your analyzer”After you enable managed trace ingestion and enroll a host, its collector sends new complete records from supported session logs to your analyzer. Uploads use HTTPS and include source identity, offsets, checksums, and collector information so the analyzer can authenticate and reconcile them.
Optional analysis-context snapshots describe what instructions, tools, or artifacts were available and which hub release was installed. The analyzer stores these with the session context in customer-owned storage.
The collector keeps a local upload ledger that records acknowledged ranges. If an upload fails, the collector retries the unacknowledged ranges on a later collection pass. A newly discovered source can upload its existing session history from the beginning. Later collection resumes from the acknowledged position. Keep local transcripts until their uploads reach the analyzer, because the collector retries from them.
Collection runs only for enabled, supported host sources. A new hub has trace_ingestion.enabled set to false. Turning the setting off, publishing, and refreshing installed plugins removes the managed hooks from those installations. Data already ingested and your deployed analyzer stay as they are.
From the analyzer to Promptless
Section titled “From the analyzer to Promptless”The analyzer sends a limited trace-status projection: identifiers, host attribution, timestamps, lifecycle and processing status, and event and turn counts. This projection excludes raw and canonical transcript content, prompts, tool activity, working directories, Git metadata, models, and source fingerprints.
Findings are a separate flow. The analyzer writes their summaries, impact descriptions, explanations, and evidence occurrences to Promptless. A model writes these descriptions, and they can refer to session content. Connected GitHub issues and remediation pull requests also make that information available to people who can access the repository.
From the analyzer to your model provider
Section titled “From the analyzer to your model provider”The analyzer sends session-derived input and relevant instruction context to the configured model endpoint. You choose the provider, endpoint, model, and authentication in the deployment configuration.
Current providers are OpenAI, Azure OpenAI, and AWS Bedrock. Available authentication depends on the provider. Bedrock can use AWS identity, and API-key configurations need the provider’s key. Hosting the analyzer on Azure or GCP does not automatically select a model provider.
Review the provider’s data-handling terms and your organization’s model-access policy for the work you plan to collect. See Deployment configuration for the available settings.
Credentials and access
Section titled “Credentials and access”| Credential or identity | Used by | Grants access to |
|---|---|---|
Deployment install token, plih_… | Your analyzer | Promptless for the configured deployment |
Per-host credential, plihost_… | An enrolled host | Your analyzer’s authenticated host endpoints |
| PostgreSQL credentials | Analyzer and migration job | The customer database and required schema operations |
| Cloud workload identity | Analyzer | The configured trace bucket and authorized model access |
| Model API key | Analyzer, for API-key authentication | The configured model endpoint |
| Analysis repository token | Analyzer | Read access to each selected instruction repository |
| Remediation repository token | An isolated remediation task | Repository-scoped operations to prepare its change |
An organization member approves enrollment in Promptless. The host caches its own credential locally and sends it to your analyzer for authenticated requests. The analyzer validates the credential through Promptless using its hash, deployment identity, and host target. A credential for one host family or deployment cannot be substituted for another.
Keep the deployment token in your cluster’s secret-management system, out of distributed plugins. Each host has its own credential, so the team shares no single secret.
Repository credentials have distinct roles. When the analyzer requests its instruction sources, Promptless issues a GitHub App token that reads each selected repository. Promptless uses the connected GitHub integration for issues and supplies a repository-scoped token for an isolated remediation task. None of these tokens is part of an uploaded trace or a published plugin.
Your operational responsibilities
Section titled “Your operational responsibilities”Choose database and bucket access, encryption, retention, backup, and restore settings according to your requirements. Configure HTTPS for host-to-analyzer traffic and use the intended network access path, such as your organization’s VPN. Limit repository and observability access to the people who need the information they contain.
Treat logs as another place where trace data can appear. The analyzer emits structured diagnostics that can include trace-related labels or analysis details. Apply your normal log access and retention controls when enabling an observability integration.
Automatic updates maintain PIG application releases and schema migrations within the installed permissions. Your team owns cloud infrastructure, including database sizing, storage, IAM, and backups, through Terraform. See GitOps ownership for the permission and ownership model.
Next steps
Section titled “Next steps”Review deployment planning with your platform team, then deploy the analyzer with Helm or a cloud recipe. Next, enroll a pilot host and verify its collection path before expanding to more users.