Network boundary
Hybrid deployment on AWS. Left: your data plane, with corporate VPN into the private subnet, or optional Internet + NLB. Right: xpander Cloud. The PrivateLink sync carries cluster identity, health status, agent configuration, and the skill schema.
us-west-2, us-west-1, eu-west-2, eu-central-1, ap-south-1. The service itself is in us-west-2 (pass --service-region us-west-2 when creating the VPC endpoint from another region).
Authentication flow
Sign-in is the only flow from the browser to xpander cloud. It carries identity, not work.Sign-in to xpander Chat. Identity goes to xpander Cloud. Everything after sign-in is browser ↔ your cluster.
chat.xpander.ai (SSO over OIDC on enterprise plans). xpander Chat then points the browser at your cluster, and chat, tasks and results move between the browser and your cluster only.
Agent runtime flow
The prompt path runs inside your cluster.Prompt flow. The task pipeline runs in your cluster. Model and skill calls leave via NAT. xpander Cloud is not on this path.
- The prompt enters through your ingress to the API, then the Agent Controller and the execution tier (
agent-worker). Agents run on Claude Code, Codex or OpenCode on the executor fleet. - Model calls go through the in-cluster AI Gateway, always on, with the organization’s or the install’s key. A call with neither key is refused with a message that names it. New runs wait for a healthy gateway.
- The skill relay calls target APIs. Model and skill calls leave your VPC via NAT, never through xpander cloud.
- Threads, task state and results go to your cluster’s PostgreSQL.
Data that leaves the on-prem installation
Everything the Hybrid data plane sends to xpander cloud, using only documented fields and public shapes. Example payloads are folded under each item.What does not leave
How the cluster talks to Cloud
Only the Agent Controller reaches xpander cloud. It authenticates withorganization_id + environment_id + the deployment-manager API key, reports heartbeats, and pulls agent, skill and MCP configuration. Other pods (agent-worker, gateway, API, MCP, brain-ingest) never call Cloud. Each location also has feature toggles (Verify the Connection), which carry no runtime payloads.
1. Cluster identification
Sent on every control-plane request.Example: identification fields and header
Example: identification fields and header
2. Health status (heartbeats)
Heartbeats drive Connection established and per-service status in Platform > Agents > Runtime > Locations. They use the same credentials. The schema is not published, so the example only restates what xpander Chat shows, not the wire format:Example: heartbeat (schema not published)
Example: heartbeat (schema not published)
3. Agent metadata (stored in Cloud, pulled by the cluster)
Agent definitions are authored in xpander cloud and pulled as catalog metadata, not invocations. The shape is the public List Agents response, redacted:Fields and example: List Agents response, redacted
Fields and example: List Agents response, redacted
4. Skill schema (pulled)
Each skill operation is pulled as a function-call definition: name, description and parameter schema, never the tokens. Skill tokens stay in Kubernetes secrets (per-person MCP tokens: below). Redacted Jira example:Fields and example: Jira skill operation, redacted
Fields and example: Jira skill operation, redacted
5. MCP configuration (pulled)
MCP endpoints are pulled with the agent definition. Attach payloads fromAdd Agent Tool:
Fields and example: MCP attach payloads
Fields and example: MCP attach payloads
Per-person MCP sign-in tokens
On Hybrid, per-person sign-in for MCP connectors runs in xpander cloud. The chart has no sign-in service.Calls that run through xpander cloud
6. xpander Chat sign-in identity (browser → Cloud)
Sign-in is browser to Cloud, not cluster egress (see Authentication flow). Cloud holds this for each user, the samecreated_by_details shape as agent metadata:
Example: sign-in identity record
Example: sign-in identity record

