Networking and identity

Overview

Enrolled hosts send traces to an HTTPS endpoint in your infrastructure. The analyzer then connects to your database, trace bucket, GitHub, model provider, and Promptless. Use this guide to set up network policy, ingress routing, and proxy limits for those connections, and to give each component its own identity. Return to it when uploads fail at a proxy or a cloud agent can’t reach the analyzer.

Upload ingress

Enrolled hostsWorkstations, laptops, and agent hosts

Session traces

Trace analyzerYour HTTPS endpoint · port 443

Connections initiated by the analyzer

Trace analyzerYour cluster

Trace objects

Trace bucketYour storage · HTTPS 443

Analysis state

PostgreSQLYour database · TLS, usually TCP 5432

Findings, remediations, & analyzer status

PromptlessPromptless cluster · HTTPS 443

Hub source & proposed updates

Instruction HubGitHub repository and API · HTTPS 443

Trace digest

Model providerReuse the provider your agents use · HTTPS 443

Database and trace storage stay in your infrastructure. Arrows show who initiates each connection; requests and responses travel over that connection. The table below also covers release downloads and identity endpoints.

Allow the required paths

Allow these connections in your network policies and firewalls:

Source	Destination	Purpose
Enrolled hosts	Analyzer ingress, HTTPS 443.	Enrollment, check-ins, and trace uploads.
Analyzer and migration Jobs	Your PostgreSQL endpoint, normally TCP 5432.	Data access and schema migrations over TLS.
Analyzer	Your trace storage endpoint, HTTPS 443.	Write raw uploads and read trace objects.
Analyzer	Promptless endpoint, `https://api.gopromptless.ai` by default, HTTPS 443.	Policy, status, findings, and remediation synchronization.
Analyzer	GitHub repositories and required GitHub API endpoints, HTTPS 443.	Read the selected instruction repositories and coordinate connected workflows.
Analyzer	Your model endpoint, HTTPS 443.	Analyze sessions using your provider account.
Supervisor and cluster nodes	Release metadata and artifact registries, HTTPS 443.	Resolve releases and pull images.
Workloads using federation	Your cloud’s identity endpoints.	Obtain and refresh workload credentials.

Also allow cluster DNS and your platform’s required control-plane traffic. Apply network policies to migration Jobs as well as long-running pods. A private storage endpoint is reachable only with matching private DNS and routing.

Route collector requests

The analyzer Service listens on port 8080. The bootstrap chart’s Ingress routes exactly these paths to it. Route the same paths through any HTTPS gateway or proxy in front of the Ingress:

Method	Exact path	Purpose
GET	`/healthz`	Process health.
GET	`/v0/host-enrollment/policy`	Collector policy for an enrolled host.
POST	`/v0/host-enrollment/check-ins`	Host check-ins.
POST	`/v0/cloud-enrollment/leases`	Cloud agent enrollment and lease renewal.
POST	`/v0/traces/batches`	Trace uploads, with a `target` query parameter.

Keep other analyzer routes, such as /readyz, off the endpoint. Kubernetes Ingress routes by path only. If your policy requires method restrictions, apply them at a gateway.

Enrolled hosts send their host credential in an Authorization: Bearer header. Cloud agents also send an X-Promptless-Producer-Token header. Forward both headers to the analyzer unchanged, and keep their values out of proxy logs. The analyzer checks these credentials itself. TLS and gateway access controls add a layer in front of that check.

Hosts use the configured https:// address without a path, and cloud agents reject redirects. Serve the collector routes over HTTPS at that hostname. If you expose plain HTTP, redirect it to HTTPS at the controller.

Set request limits and timeouts

Every proxy and load balancer on the upload path must accept the collector’s requests:

Request body. Set each proxy’s limit to at least 10 MiB. The collector sends one compressed, base64-encoded source chunk per upload, with an encoded body of at most 10 MiB. The analyzer accepts encoded bodies up to twice its decoded trace-batch limit plus 64 KiB. With the default 256 MiB decoded limit, that’s about 512 MiB. The examples set 256m for ingress-nginx, which sits between the 10 MiB minimum and the analyzer’s limit. AWS lists no request-body quota for Application Load Balancers with IP targets.
Timeouts. Keep read and idle timeouts at 10 seconds or more. The collector waits up to 10 seconds for each network read, and retries later from its local ledger when a request fails. The default 60-second proxy read timeout of ingress-nginx and the default 60-second idle timeout of an ALB both meet this.

For ingress-nginx, set the limit in the bootstrap values:

ingress:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "256m"

Use the equivalent setting for other controllers and for any gateway, CDN, or corporate proxy in front of them. A proxy with a limit below 10 MiB can reject uploads with HTTP 413 while /healthz still succeeds.

Reach the analyzer from cloud agents

A private endpoint works when every enrolled host can reach it, for example over your VPN. Cloud agents run in a provider’s sandbox and need an HTTPS endpoint reachable from that sandbox’s network. Claude Tag’s Agent Proxy blocks private IP ranges even when the destination hostname is allowed. A cluster Service or a VPN-only endpoint can’t serve Claude Tag.

For Claude Tag, expose the analyzer through a public HTTPS Ingress, such as an internet-facing ALB.
In the runner’s sandbox network policy, allow the exact analyzer hostname and the methods listed in Route collector requests. For Claude Tag, see Claude Tag network access.
Get an authorized cloud enrollment credential from Promptless for the agent’s collector. Network access alone doesn’t enroll a cloud agent.
From the actual sandbox, verify the certificate, the health response, and a trace upload before you rely on collection.

Separate identities by purpose

Give each component its own credential or identity, scoped to one purpose:

Identity	Scope
Host enrollment credential	An individual enrolled host’s collection access.
Deployment installation token	The analyzer installation’s connection to Promptless.
Analyzer workload identity	Its configured trace objects and, if selected, authorized model access.
PostgreSQL role	The dedicated PIG database and schema migrations.
Instruction repository access	GitHub App tokens Promptless supplies for the selected instruction repositories, scoped to Contents read.
Supervisor ServiceAccount	PIG application resources and its own updates within installed Kubernetes RBAC.
Terraform execution identity	Reviewed cloud infrastructure changes made by your platform team.

Keep cloud management privileges with your Terraform workflow; the supervisor doesn’t need them. When the analyzer uses one workload identity for both storage and model access, grant each permission separately.

Deliver application credentials through your secret manager, rotate them in place, and keep the Secret names that PIGDeployment references. Keep TLS certificate renewal in your existing certificate-management workflow.