# Architecture

Daevix has three main components: the **control plane**, one or more **enclaves**, and **agents**. They communicate in a strict hierarchy - and the most important rule is that **agents never talk directly to the control plane**.

```
┌──────────────────────────────────────────────────────────────────┐
│                        Control Plane                             │
│                       (Daevix-hosted)                            │
│                                                                  │
│   Identity · Policy · Audit · Operator API · Hooks · Secrets     │
└──────────────────────────────┬───────────────────────────────────┘
                               │
                               │ TLS (enclave ↔ control plane)
                               │
                ┌──────────────┼──────────────────┐
                ▼              ▼                  ▼
        ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
        │  Enclave       │ │  Enclave       │ │  Enclave       │
        │  (Org A)       │ │  (Org B)       │ │  (Org C)       │
        └───────┬────────┘ └────────────────┘ └────────────────┘
                │
                │ provisions + manages agents
                ▼
        ┌──────────────────────────────────────────────────┐
        │  Agent hosts                                     │
        │  ┌───────────┐  ┌───────────┐  ┌───────────┐    │
        │  │  Agent 1  │  │  Agent 2  │  │  Agent 3  │    │
        │  └───────────┘  └───────────┘  └───────────┘    │
        │                                                  │
        │  Agents only talk to the enclave                 │
        │  (never directly to the control plane)           │
        └──────────────────────────────────────────────────┘
```

> **What you operate today:** nothing in this diagram. Daevix runs the control plane and the enclave as a managed service, and you create and manage agents through the `dvx` CLI. The architecture still matters - it's what makes the platform's security guarantees hold - but there's no infrastructure for you to stand up.

## Communication topology

A key architectural constraint: **agents never communicate directly with the control plane.** The enclave is the agent's sole point of contact with the platform.

```
Control Plane ◄────► Enclave ◄────► Agent
                       ▲
                       │
              Agents only know
              about the enclave
```

This design provides:

- **Simpler agent networking** - Agents only need network access to the enclave, not to an external endpoint. The enclave sits close to the agents.
- **A strong security boundary** - The enclave mediates all communication. An agent cannot reach the control plane or manipulate it directly.
- **Offline resilience** - If the control plane is temporarily unreachable, agents keep operating. The enclave caches policy, queues audit logs, and serves credentials from local state.
- **Reduced attack surface** - Compromising an agent does not hand an attacker a path to the control plane. The enclave is the choke point, and it validates every request.

## Component responsibilities

### Control plane

The central management layer. It holds the canonical state of your fleet and is where policy, identity, and audit live.

| Responsibility | What it does |
|----------------|--------------|
| **Identity registry** | Canonical store of all agent identities - state, metadata, and lifecycle. |
| **Policy engine** | Defines and distributes what agents may do and which controls are required. |
| **Audit store** | Aggregates audit logs from enclaves for query, alerting, and compliance reporting. |
| **Operator API** | The API behind the `dvx` CLI for managing agents, viewing status, and configuring hooks. |
| **Hooks & secrets** | Stores provisioning hooks and briefly escrows hook-generated secrets until the agent retrieves them at bootstrap. |

### Enclave

The on-premises component that sits next to your agents. It is the agent's sole platform touchpoint.

| Responsibility | What it does |
|----------------|--------------|
| **Compute provisioning** | Provisions agent hosts (cloud APIs, hypervisors, Kubernetes). |
| **Policy enforcement** | Applies control-plane policy to the local environment. |
| **Audit forwarding** | Collects audit logs from agent hosts and forwards them to the control plane. |
| **Hook execution** | Runs provisioning and deprovisioning hooks in the context of your environment. |
| **Agent identity** | Issues short-lived platform JWTs (ES256, 5-minute lifetime) to agents, and handles bootstrap and credential renewal. |

### LLM proxy

The LLM proxy sits on the enclave side, between agents and LLM providers:

```
Agent ──JWT──► LLM proxy ──API key──► LLM provider (Anthropic, etc.)
```

It authenticates the agent's JWT, injects the provider credential (the agent never sees the API key), enforces content policy, and logs every request and response for audit.

### Agent

The agent process runs on a Linux host and is **untrusted by design**:

- Boots with only an enclave URL and a single-use bootstrap token.
- Exchanges the token for an identity bundle (JWT + refresh token + secrets).
- Runs a renewal loop to keep its short-lived identity current.
- Communicates only with the enclave - never with the control plane.

The default agent runtime is `dvxir`, but the platform's identity and security model works regardless of what code runs inside the host. See [Agent Lifecycle](/agent-lifecycle/) for the full flow from creation to decommission.