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

# Architecture Overview

> Hexr is a 5-layer runtime platform that provides cryptographic identity, secure credential exchange, and full observability for every AI agent process.

## The Big Picture

Hexr wraps your AI agent in production-grade infrastructure automatically. When you write `@hexr_agent` and run `hexr deploy`, your single Python file becomes a fully instrumented Kubernetes workload with:

* **Cryptographic identity** (SPIFFE X.509 + JWT certificates)
* **Mutual TLS** to every other service (via Envoy sidecar)
* **Authenticated cloud credentials** (AWS, GCP, Azure — no API keys in code)
* **Distributed tracing** (OpenTelemetry spans for every operation)
* **Agent-to-agent communication** (JSON-RPC 2.0 over mTLS)
* **Policy enforcement** (OPA at every service boundary)

***

## Five-Layer Platform Stack

Every Hexr deployment — cloud or self-hosted — consists of these five layers, each building on the one below:

<AccordionGroup>
  <Accordion title="Layer 1: Identity Foundation" icon="fingerprint">
    The trust root. Every process in the cluster gets a cryptographic identity.

    | Component            | Purpose                                                                                   |
    | -------------------- | ----------------------------------------------------------------------------------------- |
    | **SPIRE Server**     | Certificate authority. Issues X.509 and JWT SVIDs. PostgreSQL-backed.                     |
    | **SPIRE Agent**      | DaemonSet (one per node). Handles workload attestation and SVID rotation.                 |
    | **Auto-Registrar**   | Watches for pods with `hexr.io/*` labels. Creates SPIRE registration entries per-process. |
    | **OIDC Discovery**   | JWKS endpoint for federated auth with AWS STS, GCP WIF, Azure AD.                         |
    | **Pod UID Attestor** | Custom SPIRE plugin. Reads process context files for per-process selectors.               |
    | **File Collector**   | DaemonSet. Forwards process context JSON from host paths to Auto-Registrar.               |
  </Accordion>

  <Accordion title="Layer 2: Observability" icon="chart-mixed">
    Full telemetry pipeline — traces, metrics, and dashboards for every agent operation.

    | Component          | Purpose                                                                  |
    | ------------------ | ------------------------------------------------------------------------ |
    | **OTel Collector** | OTLP gRPC/HTTP aggregation. Receives from SDK + Envoy proxies.           |
    | **Prometheus**     | Metrics storage. 11+ scrape targets across system and tenant namespaces. |
    | **Jaeger**         | Distributed tracing. Cross-agent span correlation.                       |
    | **Grafana**        | 42 panels across 2 dashboards: platform overview + A2A communication.    |
  </Accordion>

  <Accordion title="Layer 3: Platform Services" icon="cubes">
    The runtime services that your agents interact with transparently.

    | Component               | Port    | Purpose                                                                      |
    | ----------------------- | ------- | ---------------------------------------------------------------------------- |
    | **Hexr Vault**          | 8091    | SPIFFE-native secrets. AES-256-GCM encryption. OPA-enforced isolation.       |
    | **Hexr Gateway**        | 8090    | OpenAPI → MCP tool adapter. Registers tools, injects credentials from Vault. |
    | **Credential Injector** | 8080    | JWT-SVID → AWS STS / GCP WIF / Azure FT exchange. 3-tier credential cache.   |
    | **A2A Sidecar**         | 8090    | JSON-RPC 2.0 inter-agent protocol. Valkey-backed task state.                 |
    | **Sandbox**             | 8092    | Firecracker microVM code execution + headless Chromium browser.              |
    | **LLM Guard**           | 8000    | Prompt injection detection, secret scanning, invisible text detection.       |
    | **Envoy Proxy**         | 15001/6 | mTLS mesh. Certificate rotation via SPIRE SDS.                               |
    | **Valkey**              | 6379    | 3-node HA. Credential L2 cache + A2A task state.                             |
  </Accordion>

  <Accordion title="Layer 4: Developer Experience" icon="code">
    The SDK and CLI that developers interact with directly.

    | Component        | Purpose                                                                        |
    | ---------------- | ------------------------------------------------------------------------------ |
    | **Python SDK**   | `@hexr_agent`, `hexr_tool()`, `hexr_llm()`, `hexr.vault`, `hexr.gateway`, etc. |
    | **CLI**          | `hexr build`, `hexr push`, `hexr deploy`, `hexr audit`, `hexr login`           |
    | **Private PyPI** | SDK distribution. Agents install from private registry during pod init.        |
  </Accordion>

  <Accordion title="Layer 5: Management" icon="gauge-high">
    The dashboard and APIs for operators and administrators.

    | Component             | Purpose                                                                     |
    | --------------------- | --------------------------------------------------------------------------- |
    | **Dashboard**         | Next.js web UI. Agent inventory, identity graph, compliance, traces, admin. |
    | **Cloud API**         | Tenant management, HCU metering, API keys, waitlist, invite codes.          |
    | **Identity Graph**    | WebGL-rendered graph of all agents, services, and trust relationships.      |
    | **Compliance Engine** | 5 frameworks (SOC 2, NIST, ISO, PCI, EU AI Act) mapped to OPA policies.     |
  </Accordion>
</AccordionGroup>

***

## How Identity Flows

From decorator to production-ready mTLS, the identity cascade has six stages:

<Steps>
  <Step title="hexr build" icon="hammer">
    The CLI performs **AST analysis** on your Python source. It discovers every `@hexr_agent`,
    `hexr_tool()`, and `hexr_llm()` call, then generates a Dockerfile, Kubernetes manifests,
    and per-process context JSON files.
  </Step>

  <Step title="hexr deploy" icon="upload">
    Applies Pod manifests + ConfigMaps to your cluster via `kubectl apply`.
  </Step>

  <Step title="Auto-Registrar detects pod" icon="eye">
    The Auto-Registrar watches for pods with `hexr.io/*` labels. When your pod appears,
    it reads the process context ConfigMaps and creates a **SPIRE registration entry**
    for each discovered process role.
  </Step>

  <Step title="Pod starts (4 containers)" icon="cubes">
    Init container installs SDK. Then agent, envoy-sidecar, a2a-sidecar, and pid-mapper
    all start. The agent writes a marker file to the shared volume.
  </Step>

  <Step title="SVID issued" icon="certificate">
    The agent process calls the SPIRE Workload API (via the shared socket). SPIRE matches
    the workload against the registration entry and issues an **X.509-SVID** with the
    per-process SPIFFE ID: `spiffe://trust-domain/agent/{tenant}/{agent}/{role}`.
  </Step>

  <Step title="mTLS ready" icon="shield-check">
    Envoy loads the SVID via SDS. All inbound and outbound traffic is now **mutual TLS**.
    The agent can call other services, exchange credentials, and communicate with other agents.
  </Step>
</Steps>

<Info>
  **Per-process, not per-container.** Hexr assigns SPIFFE identities to individual agent processes
  within a container — not just the pod or container. This enables identity attribution for
  multi-agent frameworks where multiple agents run in a single process tree.
</Info>

***

## Agent Pod Architecture

Every deployed agent runs as a Kubernetes Pod with **1 init + 3 runtime containers**, connected by shared volumes.

<Tabs>
  <Tab title="Containers">
    <Steps>
      <Step title="Init: install-hexr-sdk" icon="download">
        Pulls the Hexr SDK from the private PyPI registry into a shared volume.
        Runs once before any runtime container starts.
      </Step>

      <Step title="agent · :8080" icon="robot">
        **Your Python code.** Runs your `@hexr_agent`-decorated function. Listens on `:8080` for
        inbound A2A bridge calls. Reads SVID from SPIRE socket for identity.
      </Step>

      <Step title="envoy-sidecar · :15001/:15006" icon="shield-halved">
        **mTLS proxy.** Terminates inbound TLS on `:15006`, initiates outbound mTLS on `:15001`.
        Loads X.509-SVIDs via SPIRE SDS. Zero-code mesh encryption.
      </Step>

      <Step title="a2a-sidecar · :8090" icon="arrows-left-right">
        **Agent communication.** JSON-RPC 2.0 dispatch. Task state persisted in Valkey.
        SSE streaming for real-time updates. Prometheus metrics exported.
      </Step>

      <Step title="pid-mapper · hostPID: true" icon="fingerprint">
        **Identity mapper.** Reads `/proc` with host PID namespace access. Maps container PIDs
        to host PIDs. Writes process context JSON for SPIRE workload attestation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Shared Volumes">
    | Volume                 | Mount Path                      | Purpose                                                                  |
    | ---------------------- | ------------------------------- | ------------------------------------------------------------------------ |
    | **spire-agent-socket** | `/run/spire/sockets/agent.sock` | SPIRE Agent Workload API — all containers fetch SVIDs through this       |
    | **hexr-context**       | `/tmp/hexr-context/`            | Process context JSON files written by pid-mapper, read by SPIRE attestor |
    | **host-hexr-context**  | `/host-hexr-context/`           | Host PID namespace mapping — pid-mapper writes, File Collector forwards  |
  </Tab>

  <Tab title="Network Flow">
    ```
    Incoming Request
         │
         ▼
    envoy-sidecar (:15006)     ◄── terminates TLS, verifies peer SVID
         │
         ▼
    agent (:8080)              ◄── your @hexr_agent function runs
         │
         ├──► envoy-sidecar (:15001) ──► external APIs (mTLS)
         │
         └──► a2a-sidecar (:8090)   ──► other agent pods (JSON-RPC 2.0)
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Per-Process Identity" icon="id-card" href="/architecture/per-process-identity">
    Deep dive into how SPIFFE IDs are assigned to individual agent processes.
  </Card>

  <Card title="Credential Exchange" icon="right-left" href="/architecture/credential-exchange">
    How the 3-tier cache delivers sub-millisecond cloud credentials.
  </Card>
</CardGroup>