Private Agent
Connect private evidence sources to Cloud or your self-hosted instanceEdit
Connect private services to AI SRE investigations through an outbound-only, read-only agent. For test execution workers on separate servers, see Multi-Server.
Prerequisites
| Requirement | Details |
|---|---|
| Permission | Organization owner or admin. The server requires the connector-configure permission; an org-wide agent also needs organization-level rights. Settings → Organization is not shown to other roles |
| Host | Docker Engine with Compose v2 that can reach Supercheck and your provider endpoints |
| Network | Outbound HTTPS to the Supercheck API, with no browser challenge in front. No inbound ports for remote agents; colocated agents use the private Docker network |
Use the supplied Compose file: it keeps the agent non-root, read-only, and capability-free.
Set up
Register the agent
In your Cloud or self-hosted dashboard, select the project and open Settings → Organization → Private Agents → Register agent. Keep project scope selected unless the agent must serve other projects.
Copy the Agent ID and Registration token, and start the agent within 15 minutes, before the token expires.
Start the agent
In your existing deploy/docker/.env, add the credentials and the profile, keeping any existing profiles:
COMPOSE_PROFILES=https,private-agent
PRIVATE_AGENT_ID=your-agent-id
PRIVATE_AGENT_TOKEN=your-registration-tokenFor a local HTTP install use COMPOSE_PROFILES=private-agent. Then, from that directory:
sudo docker compose up -d private-agentConnect a provider
Confirm the agent shows connected. In the same project's Settings → Organization → Integrations, add a connector, select Private Agent, and choose this agent.
Enter a container-reachable provider endpoint and a read-only credential, then validate the connector and test a known-result query. See Connectors for provider requirements and Connector limits.
Investigate
Link the connector's service to an incident and run an investigation with Include live sources, or use Copilot.
Agent status and options
| Status | Meaning |
|---|---|
| pending | Registered or rotated, not connected yet |
| connected | Heartbeats are arriving |
| disconnected | No heartbeat for 90 seconds |
| unhealthy | Connected, but it reported a problem |
| disabled | Turned off permanently; register a new agent to replace it |
Preserve the private-agent-state volume; do not use down -v during maintenance.