Skip to content

For the complete documentation index, see llms.txt.

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.

  • 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.
DataDestinationPurpose
Instruction assets and plugin definitionsYour Git repository and CIReview and publish shared instructions
Compiled pluginsInstalled agent hostsMake instructions available during agent work
Native transcript recordsYour analyzer and trace bucketPreserve the source evidence for analysis
Canonical traces and optional context snapshotsYour customer-owned storageReconstruct sessions and the context available to an agent
Host attribution, ingestion progress, and analysis stateYour PostgreSQL databaseTrack uploads and coordinate processing
Session and instruction contextYour configured model providerAnalyze behavior and prepare proposed improvements
Trace identity, counts, and processing statusPromptlessShow collection and analysis progress
Findings, evidence summaries, and remediation statePromptless and connected GitHub issues or pull requestsExplain problems and review proposed changes
Configured operational telemetryYour selected observability systemsDiagnose 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.

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.

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.

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.

Credential or identityUsed byGrants access to
Deployment install token, plih_…Your analyzerPromptless for the configured deployment
Per-host credential, plihost_…An enrolled hostYour analyzer’s authenticated host endpoints
PostgreSQL credentialsAnalyzer and migration jobThe customer database and required schema operations
Cloud workload identityAnalyzerThe configured trace bucket and authorized model access
Model API keyAnalyzer, for API-key authenticationThe configured model endpoint
Analysis repository tokenAnalyzerRead access to each selected instruction repository
Remediation repository tokenAn isolated remediation taskRepository-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.

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.

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.