Agent or connector
When a customer asks you to reach their private systems, a small agent is often all that runs in their environment. It sits next to a system you can only reach from inside their network, such as a Kubernetes API, a private database, or servers on site, and connects out to your cloud.
Architecture diagram. Left: Your cloud, Your API, Alien manager. Right: Customer network containing Kubernetes cluster containing cluster agent; Kubernetes API; private subnet containing connector; database; site servers containing agent (Daemon); sensors.
The agent works locally and returns only the result. Releases, commands, and logs all travel over connections the agent opens itself.
When it fits
- It fits when the buyer says "our cluster and databases aren't reachable from the internet", or when the work happens on specific hosts or devices, such as employee laptops. AI agents use it for tool calls; data connectors and security scanners use it to run queries.
- It doesn't fit when the agent ends up storing customer data that your product then serves. That is a data plane.
- There may be no agent at all when the work is stateless code your product runs for the customer. Your backend can create sandboxes in the customer's account and drive them directly. See Sandboxes.
The usual alternatives are a VPN, a public endpoint on the customer's database with an allowlist, or a connector the customer runs and you can't update. Security teams tend to refuse the first two, and the third drifts onto old versions.
What runs where
The agent is one small workload. Your API, its database, and everything else stay in your cloud. The resource follows from how the agent runs:
| Agent | Resource | Example |
|---|---|---|
| Answers calls from your backend, idle otherwise | Worker with .commandsEnabled(true), scales to zero | A database connector, an AI agent's tool calls |
| Watches something all the time | Container | A cluster agent that reports inventory |
| One process per host or device | Daemon on machines or local | A site agent next to sensors, an agent on employee laptops |
A connector next to a database reads the connection details from the customer's own secret store. It exposes named operations such as orders-by-status, not free-form SQL.
At initial setup, the one-time step the customer's admin runs, the admin places the deployment in the network that reaches the database with --network byo. See Networking.
What crosses
Instructions go in and results come out, over connections the agent opens. The agent returns results in either or both of these ways:
- The agent calls your API. It posts results on a schedule or when something changes. Pass your API's URL in, and have the agent authenticate with a credential the customer provides or one you issue at enrollment.
- Your backend sends commands. Your backend sends a named command with
CommandsClient. The agent leases it over outbound HTTPS, runs your handler, and returns the result.
Name exactly which results leave the environment, and keep them small: the inventory, the query result, or the reading your product needs, not the raw data behind it.
Updates and operations
Each release reaches the agent over its outbound connection, with no one logging in.
- Kubernetes. Initial setup is one
helm install. The chart creates the enrollment token and a read-only ClusterRole, and later releases arrive without ahelm upgrade. - Machines. Hosts keep running the last release they accepted when they lose their connection.
When the agent is unreachable, the feature that needs the private system returns an error. The rest of your product keeps working.
Before production:
- Limit what the agent can do. Read-only Kubernetes verbs, a read-only database user, named commands instead of arbitrary input.
- Plan for disconnects. Buffer results and retry when your API is unreachable. Make your API accept the same report twice.
- Keep commands read-only. For actions that change the environment, such as restarting a workload, use Remote Operator operations, which carry an approval policy.
Examples
- Query a private database: a connector beside a database you can't reach, exposing only the queries you allow.
- Kubernetes agent: an agent in a cluster.
- Agent on employee devices: an agent on laptops.
- Remote tools for an AI agent: an AI agent's tool calls.
Next
- Commands: send commands from your backend to the agent.
- Linux servers: run the agent on the customer's own hosts.
- Connect your backend: every path between your backend and a deployment.
Control plane ⇄ Data plane
Keep the shared part of your product in your cloud and run the part that handles customer data wherever each customer needs it, from a shared deployment in your cloud to the customer's own account.
Whole product
Deploy every service and its storage into the customer's environment, including air-gapped sites, and know what you give up compared to a split.