Connect a private network

Install a private agent, confirm its heartbeat, then prove it can read your system.

How-to · Updated 2026-10-26 · Describes release 0.1.164

The private-network agent

A private agent runs inside the customer's network and polls this platform over outbound HTTPS. It needs the platform URL, a workspace-scoped agent token, access to the displayed image registry, access to its data endpoints and a usable model gateway configuration.

Open Private network agent on Alert intake & tokens (in the product: /portal/tokens). Create a token, complete the installation fields and copy the Docker or Kubernetes command. Keep the token private. A token is not an installed agent.

Verify two things: a recent last seen timestamp, then a successful real Test of a private read connection. A queued test is still waiting for evidence. Execution-only credentials are excluded from private-agent read checks. An opted-in AWS/Azure execution connection can perform a safe identity/read check from the control plane; no check certifies future write permissions. Supported agent versions execute investigations, discovery and contextual conversations through the platform protocol; use the image specified by your deployment.

Before you start

Choose a VM with Docker or a Kubernetes cluster inside the network that can reach your datasource. It needs outbound HTTPS to this platform, DNS and access to the agent image registry. Cloud and data endpoints must also be reachable from that machine. No inbound port to the agent is required.

Your account needs datasources.manage. Have the registry login or image-pull secret ready if the image is private. The displayed image must match the running platform's agent protocol; use the command supplied by your deployment. Roll the agent forward with every platform release: an older agent ignores settings it does not know — the Singapore regulated flag or the runbook-route offer, for example — and agents report no version.

Connection checks work without a model. Before using chat or running investigations, configure a model gateway reachable from the agent, or explicitly share your workspace gateway in AI models.

Workspace chat runs on a private agent only when its token was created with Answers workspace chat. Such an agent receives every member's chat questions and recent history and writes the answers, so only a member with members.manage (the owner) can tick it; a token created without it never receives a chat turn. After a chat-serving agent first connects, workspace chat stays on private agents. Revoking its token does not move chats to the hosted platform. If chat is waiting for an agent, reconnect or replace the agent and check its model connection. Agent tokens that had connected before this option existed keep answering chat and are marked answers chat in the token list. The option cannot be cleared on an existing token: to take chat away from one, revoke it and create a replacement without Answers workspace chat.

1. Create the agent credential

Open Alert intake & tokens (in the product: /portal/tokens) and find Private network agent. Give it a location name, such as singapore-vpc, and create its token. Keep this page open: the full token is shown once.

To retire a token, select the trash button on its row, then Revoke token in the Revoke agent token dialog. The agent using it stops authenticating at once and the revoke cannot be undone, so the dialog asks first; Cancel changes nothing, and a refusal from the platform stays in the dialog. Create a new token and reinstall the agent to replace it.

2. Run the generated installation

Select Docker for a VM, or Kubernetes for a cluster. The platform supplies the agent image; if it is missing, a platform administrator must publish it in Platform defaults → Customer connection setup. Complete the registry and model fields that apply to your environment, then copy the complete command and run it from your terminal with access to that machine or cluster.

The command uses this platform's URL and the new workspace-scoped token. An existing token's plaintext cannot be recovered; provide the token you hold when generating a replacement installation command. Do not share a command containing the token in a ticket or chat.

3. Confirm two separate results

Agent connected: its token row shows a recent last-seen time. This proves it can authenticate and poll the platform.
Read connection verified: choose Investigate only in Data sources (in the product: /portal/datasources), then Connect and verify. Wait for the private agent's read result. This proves that the agent can reach the system and perform the reported check.

A heartbeat without a successful read-connection test is incomplete setup. If it stays offline, check container logs, outbound HTTPS, the exact platform URL, registry access and whether the token was revoked.

4. Start the operating flow

Run Estate x-ray (in the product: /portal/xray) on the verified read source, use its reviewed context, then send a test alert. Read the recorded investigation before connecting production alerts.

Write access is optional. Use a separate Approved changes only (separate credential) connection or a shared credential, then explicitly enable Allow use for approved plans. Review its exact operation and target on the incident or Change. Private-agent verification covers readable connections, not an execution-only credential. AWS/Azure execution access can have a safe control-plane identity check; neither that check nor a successful read proves every write permission.

Keyless authentication is a separate step

For AWS, a workspace with an installed private-network agent is outside any-account mode: reads run on the agent’s own role, which platform staff publish as the reader together with a prepared read/write pair per account.

The agent token lets the container talk to AIOps. It does not grant AWS, Azure, GCP, Kubernetes or SSH access. Configure the supported cloud workload identity or the datasource credential as well. Google Cloud on this shared deployment requires a dedicated customer service-account JSON key, including when a private agent is installed.

The private agent must also have a usable model gateway configuration. A platform token does not automatically grant model-provider access; follow the installation panel's gateway readiness details. Use AWS, Azure, GCP, Kubernetes or on-premises for the next credential step.