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

# System Architecture

> The services in a self-hosted Asymptote deployment, how telemetry flows through them, and the security model.

> [!NOTE]
>
> **Planned release.** Self-hosted Asymptote is in development and offered to design partners through a Private Deployment engagement; the Helm chart and Terraform modules described in this section are not generally available yet. This section describes the planned release: chart names, values keys and paths may change before it ships. Today's Asymptote Cloud dashboard uses hosted services for sign-in and product analytics; the self-hosted release replaces them, as described in [System Architecture](https://docs.asymptotelabs.ai/self-hosting/system-architecture.md#hosted-services-in-asymptote-cloud). [Contact us](https://asymptotelabs.ai/contact) to take part.

> [card] [Kubernetes Deployment](https://docs.asymptotelabs.ai/self-hosting/kubernetes.md)
>
> Install the Helm chart in your cluster.

> [card] [Terraform](https://docs.asymptotelabs.ai/self-hosting/terraform.md)
>
> Create the cluster and services on AWS, Google Cloud or Azure.

***

## Overview

```mermaid theme={null}
flowchart LR
  subgraph Endpoints["Your endpoints"]
    Beacon["AI agents and Beacon"]
  end
  subgraph Cluster["Your Kubernetes cluster"]
    Ingest["ingest"]
    Policy["policy"]
    Web["web"]
    API["api"]
    Loader["loader"]
    Workers["workers"]
    CH[("ClickHouse")]
  end
  subgraph Cloud["Your cloud account"]
    Bucket[("Object storage")]
    Queue["New-object notifications"]
    PG[("PostgreSQL")]
    LLM["LLM endpoint"]
    IdP["Identity provider"]
  end
  Beacon -->|"telemetry"| Ingest
  Beacon -.->|"live checks"| Policy
  Ingest --> Bucket
  Bucket --> Queue
  Queue --> Loader
  Loader --> CH
  Web --> API
  API --> CH
  API --> PG
  Policy --> LLM
  Workers --> CH
  Workers --> LLM
  Web --> IdP
```

## Services

### Core services

| Service | Exposed to | Function |
| - | - | - |
| `web` | Your people | The dashboard |
| `api` | `web`, and API clients | Search, timelines, fleet inventory, policies, findings and administration |
| `ingest` | Your endpoints | Checks each device's key and writes telemetry batches to object storage |
| `policy` | Your endpoints | Answers the hooks' live policy checks (`/v1/enforce`) and records decisions as findings |

### Background workers

| Service | Function |
| - | - |
| `loader` | Reads new-object notifications and loads each new object into ClickHouse, in any order |
| `workers` | Background reviews, detections, Slack finding notifications and scheduled jobs |
| `migrations` | A job that runs on each install and upgrade to migrate PostgreSQL and ClickHouse |

### Data services

| Service | Runs | Holds |
| - | - | - |
| ClickHouse | In the cluster, through the ClickHouse operator, or your own | Telemetry and inventory, for search, timelines and detections |
| PostgreSQL | Your cloud's managed PostgreSQL | Users, devices, policies, findings and audit records |
| Object storage | Your bucket | Raw telemetry, the system of record |

## Data flow

1. Beacon on an endpoint records agent activity and sends batches to `ingest` over HTTPS, with the device's own key.
2. `ingest` checks the key, stamps the device and organization on each event, and writes the batch to your bucket.
3. The bucket posts a notice for the new object. `loader` reads it, fetches the object and loads it into ClickHouse. Retried batches collapse on Beacon's deterministic event IDs.
4. `web` and `api` read ClickHouse for search and timelines, and PostgreSQL for everything else.
5. When enforcement is on, the hooks ask `policy` before a prompt or tool call goes ahead, and `policy` asks the LLM endpoint when a policy needs a judgment.
6. `workers` review recorded sessions, raise findings, and post them to Slack if you turned that on.

## Network requirements

### Inbound

| From | To | Why |
| - | - | - |
| Your endpoints | HTTPS to `web` and `api` | `beacon login` and device enrollment (`beacon endpoint connect`) |
| Your endpoints | HTTPS to `ingest` and `policy` | Telemetry upload and live policy checks |
| Your people | HTTPS to `web` | The dashboard |

Expose these on the internet, or only on your private network or VPN.

### From the cluster to your cloud account

Use private endpoints (AWS PrivateLink, Private Service Connect, Azure Private Link) to keep this traffic off the internet.

| To | Used by |
| - | - |
| PostgreSQL | `api`, `ingest`, `policy`, `workers`, `migrations` |
| Object storage | `ingest` (write), `loader` (read) |
| New-object notifications (SQS, Pub/Sub or the Storage queue) | `loader` |
| Secrets Manager, Secret Manager or Key Vault, and KMS | The External Secrets Operator and workload identities, if you use them |

### Outbound, outside your account

| To | Required |
| - | - |
| Your identity provider | Yes |
| Your LLM endpoint | Yes |
| Slack (`slack.com`) | Only for finding notifications |
| Asymptote's container registry | Only if you pull images directly. Mirror them into your own registry, and the cluster never contacts Asymptote |
| GitHub (`api.github.com` and `objects.githubusercontent.com`) | Only for `beacon endpoint enforcement enable` and `update`, which download the enterprise Beacon package through `api`. To avoid it, deploy the enterprise package with your MDM instead |

The deployment sends no telemetry, usage analytics, license checks or reporting to Asymptote. Product analytics in the dashboard are compiled out of self-hosted images.

## Hosted services in Asymptote Cloud

Asymptote Cloud's dashboard uses two hosted services that the self-hosted release does not:

| In Asymptote Cloud | In self-hosted Asymptote |
| - | - |
| A hosted identity service for sign-in, which holds users' names, email addresses and organization membership | Sign-in directly through your identity provider over SAML 2.0 or OIDC. See [SSO](https://docs.asymptotelabs.ai/self-hosting/sso.md) |
| Product analytics (PostHog) that record dashboard usage and the signed-in user | Removed from the images; nothing is sent |

## Security model

### Authentication

| Who | How |
| - | - |
| People | Your identity provider over SAML 2.0 or OIDC. Groups map to roles. See [SSO](https://docs.asymptotelabs.ai/self-hosting/sso.md) |
| Endpoints | A key per device, issued at enrollment and stored as a hash. Revoking the device on the dashboard stops it within about a minute |
| Policy checks | A per-device enforcement token that can only ask for decisions |
| API clients | Organization API keys with scopes |

### Secrets management

The chart reads credentials from one Kubernetes secret: the license key, the PostgreSQL URL, the two key peppers (for hashing device keys and enforcement tokens), the identity provider's client secret, and, where they apply, an LLM API key and a Slack token. See [Kubernetes Deployment](https://docs.asymptotelabs.ai/self-hosting/kubernetes.md#setup). Create them yourself, or sync them from Secrets Manager, Secret Manager or Key Vault with the External Secrets Operator.

### Network security

* Every container runs as non-root with a read-only root file system.
* The chart ships network policies that allow only the traffic in the table above.
* Images are signed and come with an SBOM. Enforce the signature at admission if your cluster supports it.

### Support access

Asymptote has no access to your deployment. For a support case, you can give an Asymptote engineer temporary access in a session you open and end, or send logs yourself.

## Monitoring

### Key metrics

| What | Why |
| - | - |
| `ingest` request rate and error rate | Endpoints are uploading |
| `loader` lag (oldest unloaded object) | New telemetry reaches the dashboard |
| `policy` latency | Agents wait on each check |
| ClickHouse disk use | Retention fits the volumes |
| LLM endpoint errors and throttling | Policy checks and reviews are not failing |

### Recommended stack

Every service exposes Prometheus metrics and writes structured JSON logs. Scrape them with Prometheus or your cloud's managed Prometheus, and ship logs with the agent you already run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.