> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cockroach Aegis Security and Administration

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<Note>
  **This feature is in <InternalLink version="releases" path="cockroachdb-feature-availability">private preview</InternalLink>** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
</Note>

Security wasn't bolted onto Cockroach Aegis after the fact. It shaped how the product connects to your cluster, what it is allowed to see, and what data leaves your environment. Aegis gives you deep operational insight while keeping your application data where it belongs, inside your cluster and under your control. This page consolidates frequently asked questions about how Aegis handles data.

Aegis is designed with a security-first approach. Three design choices carry most of the weight:

* **Read-only cluster access.** Aegis runs under a dedicated SQL user scoped to cluster health and metadata, so it observes without touching your data.
* **Customer-specific data isolation.** Every customer instance is fully isolated. Your reports, cluster data, agent memory, and chat history are never visible to any other customer.
* **Strong encryption and SSO support.** Data moves over secure, outbound-only connections, and access is protected by single sign-on.

The questions cover:

* [Connecting a cluster](#connect-a-cluster), including the connector for self-hosted clusters.
* [SQL permissions and data access](#sql-permissions-and-data-access).
* [Authentication, SSO, and encryption](#authentication-sso-and-encryption).
* [Data isolation, storage, retention, and deletion](#data-isolation-storage-retention-and-deletion).
* [Auditing Aegis activity](#auditing-aegis-activity).
* [How Aegis uses AI](#how-aegis-uses-ai).

For an overview of what Aegis does, see [Cockroach Aegis Overview](/docs/continuum/aegis-overview).

For information about connecting your own agents to Aegis, see [Agentic Ecosystem](/docs/continuum/aegis-agentic-ecosystem).

## Connect a cluster

Aegis can monitor both CockroachDB Cloud and self-hosted clusters. The Aegis service itself is hosted by Cockroach Labs.

* **CockroachDB Cloud clusters.** Cockroach Labs connects your cluster to Aegis when your organization is enabled for the preview. There is nothing to install or configure.
* **Self-hosted clusters.** You run a *connector* in your environment. The rest of this section applies to self-hosted clusters.

### Where does the connector run?

The connector runs on a host in your environment that can reach your CockroachDB cluster. It connects to the cluster as a dedicated SQL user and opens an outbound, encrypted connection to the hosted Aegis service.

The connector sends observed cluster metadata to Aegis. The cluster connection string and SQL credentials stay on the connector host.

### How do I connect a cluster?

Sign in to [Aegis](https://aegis.crdb.dev/) with your CockroachDB Cloud account. When no cluster is connected yet, the workspace walks you through generating a connector token, installing the connector, creating the SQL user, and starting the connector. Connect a development, staging, or test cluster first.

Before you begin, obtain the cluster's SQL connection URL, SQL CA certificate, and DB Console URL from its connection instructions or your administrator. The connector host must be able to reach both endpoints.

You can start using Aegis without generating a workload. An initial report can describe an idle cluster, and completed check-ins can produce useful reports without recommendations. To interpret those results, see [Reports and Recommendations](/docs/continuum/aegis-overview#reports-and-recommendations).

To connect an external agent, continue with [Connect through MCP](/docs/continuum/aegis-agentic-ecosystem#connect-through-mcp).

### Do I need inbound firewall access?

Not from Aegis. The connector opens an outbound connection to the Aegis service, so neither the cluster nor the connector host needs to accept inbound connections from Aegis. The cluster does need to accept inbound connections from the connector host: the connector must reach the cluster's SQL and DB Console/metrics endpoints, so add the connector host to any cluster allowlist.

Allow outbound traffic from the connector to `aegis.crdb.dev` on port `443`. A secure WebSocket connection carries requests from Aegis to the connector and results back to Aegis over that connector-initiated connection.

Allow access to the cluster's [SQL port](/docs/stable/cockroach-start#networking) (typically `26257`) and [DB Console/metrics port](/docs/stable/cockroach-start#flags-http-addr) (typically `8080`), using the actual ports from the cluster's connection instructions. Check both paths, since a successful SQL connection only confirms the SQL path.

If a connection times out, confirm that the cluster is ready, that the hostname and port are correct, and that the allowlist matches the connector host's actual outbound source IP. VPNs and proxies can route HTTPS and database traffic through different source IPs. Check both paths with your network administrator and use narrowly scoped allowlist entries.

### What if SQL connects but metrics fail?

Check the connector log for HTTP connection, certificate, or authentication errors. Without an override, the connector uses the SQL hostname on port `8080` for the DB Console/metrics endpoint. When the actual DB Console URL differs, start the connector with `--cockroach-http-addr` set to the cluster's HTTPS DB Console base URL.

Use the cluster's public, verifiable DB Console URL when available. If its certificate is signed by a private or corporate CA that the connector does not trust, obtain that CA from your administrator and start the connector with `--cockroach-http-ca {http_ca_path}`, replacing `{http_ca_path}` with the absolute path to the trusted HTTP CA's PEM file. The SQL URL's `sslrootcert` configures SQL trust, and the HTTP endpoint can use a different CA.

This setting changes certificate verification in the local connector only. The DB Console's certificate, its server configuration, and the operating system's trust store are unchanged. Keep certificate verification enabled rather than bypassing a certificate error with `--insecure`. If TLS succeeds but authentication fails, verify that the configured SQL user and password can sign in to the DB Console.

### What happens if the connector stops?

Aegis stops collecting new observations from the cluster until the connector is running and connected again. Stored reports and recommendations remain available. To remove data, see [How do I delete my Aegis data?](#how-do-i-delete-my-aegis-data).

Run the connector under a process supervisor so that it restarts after a process or host failure.

The connector retries transient WebSocket disconnections automatically. A terminated process or a sleeping laptop needs the supervisor, or you, to bring the connector back.

## SQL permissions and data access

### What can Aegis read?

With the recommended setup, Aegis reads system metadata and observability signals, including:

* Cluster topology, configuration, and schema details such as table and index names.
* Query performance statistics, including fingerprints, latency, and execution counts.
* Index usage and workload-level index recommendations.
* Resource metrics, cluster events, and status information.

The dedicated SQL user's privileges determine what Aegis can read. With the recommended grants, that excludes application tables, and queries against tables the user cannot read will fail.

### Can Aegis change my cluster?

No. Aegis's SQL access is read-only, and this is enforced in more than one place. Every statement is checked against a read-only allowlist before it runs, every SQL session is opened read-only, and every query runs inside an explicit read-only transaction. CockroachDB rejects any write attempted in that transaction, regardless of how it is spelled or which privileges the SQL user holds. Aegis records recommendations for you to review, and never applies them or changes your application's schema or data.

You can review each recommendation and decide whether to apply changes through your normal change process. The [MCP recommendation-status operations](/docs/continuum/aegis-agentic-ecosystem#available-operations) change state in Aegis only.

### Can broader permissions expose more data?

Yes. If you grant the SQL user access to application tables, query results from those tables can reach Aegis. Keep the role scoped to the recommended metadata privileges.

### What is the impact on my cluster?

Aegis's tools run on a select set of stable interfaces, as a SQL user controlled by you. The privileges we recommend should not impact the cluster, but if they do, this user can also run at a lower quality of service (QoS) to reduce the impact on foreground traffic. Before deploying to production, evaluate the impact on a non-production cluster.

## Authentication, SSO, and encryption

### How do users sign in?

Sign in with your <InternalLink version="cockroachcloud" path="create-an-account">CockroachDB Cloud account</InternalLink>. Your Aegis workspace is associated with your Cloud organization, including when the monitored cluster is self-hosted.

### Which credentials does each connection use?

| Connection                                                          | Credential                                                                  | Purpose                                                                                                                           |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Browser or external MCP client to Aegis                             | CockroachDB Cloud sign-in; the MCP client manages its own OAuth credentials | Access the Aegis instances available to the signed-in user.                                                                       |
| Self-hosted connector to hosted Aegis                               | Connector token                                                             | Authenticate the connector to the Aegis service.                                                                                  |
| Self-hosted connector to the cluster's SQL and DB Console endpoints | Dedicated SQL user's password                                               | Read the cluster metadata allowed by that SQL user's grants. This is a SQL credential, distinct from your Cloud account password. |

Each of these credentials authenticates one connection. Each MCP client signs in on its own. For MCP client setup, see [Agentic Ecosystem](/docs/continuum/aegis-agentic-ecosystem#connect-through-mcp).

### How are connections protected?

Every connection to Aegis is authenticated and encrypted, whether from your browser, an MCP client, or a self-hosted connector. A self-hosted connector's SQL credentials remain in the environment where it runs and are never sent to Aegis.

## Data isolation, storage, retention, and deletion

### Is my data isolated from other customers?

Yes. Reports, cluster context, agent memory, and chat history are visible only within your organization. Cluster memory is scoped to the cluster it describes and is never accessible to other customers.

### Where is my data stored?

The Cockroach Labs-hosted Aegis service retains operational data, including reports, recommendations, agent memory, and chat history, while your instance is active. The hosted service is the store for these artifacts; the connector and monitored cluster hold none of them.

This retained context lets separate check-ins build on earlier observations and lets you and your agents retrieve Aegis's analysis over time.

### How do I delete my Aegis data?

Deleting an Aegis instance in the web UI deprovisions that instance and removes its associated operational data.

## Auditing Aegis activity

### How can I review what Aegis queried?

Aegis connects through a dedicated SQL user, so you can identify its activity in cluster logs and statement statistics. The Aegis [web UI](/docs/continuum/aegis-overview#find-reports-recommendations-and-activity) also exposes check-in transcripts and tool-call records.

## How Aegis uses AI

### How does Aegis use AI?

Aegis uses AI to analyze system metadata and workload signals and to produce reports and recommendations. This analysis runs against system metadata only; Aegis never reads your application data or row values, and you do not need to supply an AI model account or API key.

Your cluster metadata and interactions with Aegis are not used to train or fine-tune any AI model.

## See also

* [Cockroach Aegis Overview](/docs/continuum/aegis-overview)
* [Agentic Ecosystem](/docs/continuum/aegis-agentic-ecosystem)
* [Aegis Example Workflows](/docs/continuum/aegis-example-workflows)