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:Layer 1: Identity Foundation
Layer 1: Identity Foundation
The trust root. Every process in the cluster gets a cryptographic identity.
Layer 2: Observability
Layer 2: Observability
Full telemetry pipeline — traces, metrics, and dashboards for every agent operation.
Layer 3: Platform Services
Layer 3: Platform Services
The runtime services that your agents interact with transparently.
Layer 4: Developer Experience
Layer 4: Developer Experience
The SDK and CLI that developers interact with directly.
Layer 5: Management
Layer 5: Management
The dashboard and APIs for operators and administrators.
How Identity Flows
From decorator to production-ready mTLS, the identity cascade has six stages:hexr build
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.hexr deploy
Applies Pod manifests + ConfigMaps to your cluster via
kubectl apply.Auto-Registrar detects pod
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.Pod starts (4 containers)
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.
SVID issued
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}.mTLS ready
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.
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.
Agent Pod Architecture
Every deployed agent runs as a Kubernetes Pod with 1 init + 3 runtime containers, connected by shared volumes.- Containers
- Network Flow
Init: install-hexr-sdk
Pulls the Hexr SDK from the private PyPI registry into a shared volume.
Runs once before any runtime container starts.
agent · :8080
Your Python code. Runs your
@hexr_agent-decorated function. Listens on :8080 for
inbound A2A bridge calls. Reads SVID from SPIRE socket for identity.envoy-sidecar · :15001/:15006
mTLS proxy. Terminates inbound TLS on
:15006, initiates outbound mTLS on :15001.
Loads X.509-SVIDs via SPIRE SDS. Zero-code mesh encryption.a2a-sidecar · :8090
Agent communication. JSON-RPC 2.0 dispatch. Task state persisted in Valkey.
SSE streaming for real-time updates. Prometheus metrics exported.
pid-mapper · hostPID: true
Identity mapper. Reads
/proc with host PID namespace access. Maps container PIDs
to host PIDs. Writes process context JSON for SPIRE workload attestation.Next Steps
Per-Process Identity
Deep dive into how SPIFFE IDs are assigned to individual agent processes.
Credential Exchange
How the 3-tier cache delivers sub-millisecond cloud credentials.