Agent Pod Architecture

Pod Structure

When you run hexr deploy, your agent becomes a Kubernetes Pod with exactly four containers plus an init container:

Containers
Shared Volumes
Pod Manifest

Init: install-hexr-sdk

Installs the Hexr SDK from private PyPI into a shared volume. Ensures the SDK version matches what was used during hexr build.

agent · :8080

Your Python code. Runs your @hexr_agent-decorated function. Listens on :8080 for inbound A2A bridge calls. Connects to SPIRE Workload API for SVID.

envoy-sidecar · :15001 / :15006

mTLS proxy. Terminates inbound TLS on :15006, initiates outbound mTLS on :15001. Loads X.509-SVIDs via SPIRE SDS. Routes /.well-known/* and /a2a traffic.

a2a-sidecar · :8090

Agent communication. JSON-RPC 2.0 dispatch (message/send, message/stream, tasks/get, tasks/cancel). Task state persisted in Valkey with SETNX idempotency.

pid-mapper · hostPID: true

Identity mapper. Reads /proc with host PID namespace access. Maps container PIDs to host PIDs. Writes enriched process context JSON for SPIRE workload attestation.

Volume	Mount Path	Who Reads	Who Writes
spire-agent-socket	`/run/spire/sockets/`	Agent, Envoy, A2A	SPIRE Agent (DaemonSet)
hexr-context	`/tmp/hexr-context/`	PID Mapper	Agent (marker files)
host-hexr-context	`/host-hexr-context/`	File Collector (DaemonSet)	PID Mapper (enriched JSON)

# Generated by hexr build (simplified)
apiVersion: v1
kind: Pod
metadata:
  name: acme-research-analyst
  namespace: tenant-acme-corp
  labels:
    hexr.io/managed: "true"
    hexr.io/tenant: "acme-corp"
    hexr.io/agent-name: "research-analyst"
spec:
  hostPID: true  # Required for per-process identity
  initContainers:
    - name: install-hexr-sdk
  containers:
    - name: agent           # Your code (:8080)
    - name: envoy-sidecar   # mTLS proxy (:15001/:15006)
    - name: a2a-sidecar     # Agent comms (:8090)
    - name: pid-mapper      # PID → SPIFFE mapper

Container Details

1. Agent Container

Your Python code with the Hexr SDK. This is the only container you write code for.

Property	Value
Port	`:8080` (A2A bridge listener)
Volumes	SPIRE socket, hexr-context, shared site-packages
Env vars	`HEXR_FRAMEWORK`, `HEXR_TENANT`, `HEXR_AGENT_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`

# What runs inside this container
@hexr_agent(name="research-analyst", tenant="acme-corp")
def analyze(topic: str):
    s3 = hexr_tool("aws_s3")          # → Envoy → Credential Injector → STS
    client = hexr_llm(openai.OpenAI()) # → OTel spans emitted
    # ... your agent logic

2. Envoy Sidecar

Transparent mTLS proxy. Handles all network traffic in and out of the pod.

Property	Value
Inbound	`:15006` — terminates TLS, forwards plain HTTP to agent/sidecar
Outbound	`:15001` — initiates mTLS to other pods and services
Certificates	X.509-SVID from SPIRE via SDS (Secret Discovery Service)
Routes	`/.well-known/*` → Agent Card ConfigMap, `/a2a` → A2A Sidecar

Envoy uses syscall.Exec PID inheritance — the envoy process “becomes” the proxy while maintaining the correct PID for SPIRE attestation. This is a novel technique described in the Hexr patent application.

3. A2A Sidecar

Implements the Agent-to-Agent protocol for inter-agent communication.

Property	Value
Port	`:8090` (JSON-RPC 2.0 endpoint)
Protocol	`message/send`, `message/stream`, `tasks/get`, `tasks/cancel`
State	Valkey-backed task store with SETNX idempotency
Discovery	Serves Agent Card at `/.well-known/agent.json` via Envoy route

4. PID Mapper

Maps container PIDs to host PIDs for per-process SPIFFE identity.

Property	Value
Requires	`hostPID: true` on the Pod spec
Reads	`/tmp/hexr-context/` — marker files written by agent process
Writes	`/host-hexr-context/` — context JSON with host PIDs for SPIRE attestation

Agent writes marker

When the agent process starts, the SDK writes a marker file to /tmp/hexr-context/:

{"agent_name": "content-crew", "tenant": "acme-corp", "role": "researcher", "container_pid": 42}

PID Mapper translates

The PID Mapper reads /proc to map the container PID (42) to the host PID (83721). Writes the enriched JSON to /host-hexr-context/.

File Collector forwards

The File Collector DaemonSet reads from the hostPath volume and forwards the context to the Auto-Registrar via gRPC.

Auto-Registrar creates entry

The Auto-Registrar calls SPIRE Server’s CreateEntry API with per-process selectors (k8s:pod-uid, hexr:process-role).

SVID issued

The agent process fetches its X.509-SVID from the SPIRE Workload API, receiving a certificate with its per-process SPIFFE ID.

Shared Volumes

Three volumes connect the containers:

Volume	Mount Path	Purpose
`spire-agent-socket`	`/run/spire/sockets/`	SPIRE Workload API socket. Agent + Envoy use this for SVID requests.
`hexr-context`	`/tmp/hexr-context/`	Agent writes process identity markers. PID Mapper reads them.
`host-hexr-context`	`/host-hexr-context/`	PID Mapper writes host-PID-enriched context. File Collector reads from host.

Init Container

Before the main containers start, an init container installs the Hexr SDK:

initContainers:
  - name: install-hexr-sdk
    image: python:3.11-slim
    command: ["pip", "install", "--target=/shared/site-packages", "hexr"]
    env:
      - name: PIP_INDEX_URL
        value: "https://pypi.hexr.cloud/simple/"  # Private PyPI
    volumeMounts:
      - name: shared-packages
        mountPath: /shared/site-packages

This ensures the SDK version matches what was used during hexr build, regardless of what’s baked into the agent image.

Network Flow

How a hexr_tool("aws_s3") call flows through the pod:

Agent calls hexr_tool('aws_s3')

SDK checks L1 in-memory cache, then L2 Valkey cache. Both miss.

Agent → Envoy (localhost)

Agent sends POST /exchange to the Envoy sidecar over localhost (plaintext, same pod).

Envoy → Credential Injector (mTLS)

Envoy initiates mutual TLS to the Credential Injector in hexr-system, attaching the agent’s X.509-SVID as the client certificate.

Credential Injector verifies + checks OPA

CI verifies the JWT-SVID via SPIRE Workload API, then queries OPA: “Can this SPIFFE ID access aws_s3?”

STS exchange

CI calls AssumeRoleWithWebIdentity on AWS STS, presenting the JWT-SVID as the web identity token. AWS trusts Hexr’s OIDC endpoint.

Credentials returned + cached

Temporary AWS credentials (15min TTL) flow back through Envoy to the agent. Stored in L1 + L2 cache. SDK creates an authenticated boto3 S3 client.

Subsequent calls hit the L1 in-memory cache (~0.001ms) or L2 Valkey cache (~1-3ms), avoiding the full exchange round-trip.

Getting Started

Self-Hosted Deployment

Architecture

Security & Compliance

Agent Pod Architecture

Pod Structure

Container Details

1. Agent Container

2. Envoy Sidecar

3. A2A Sidecar

4. PID Mapper

Shared Volumes

Init Container

Network Flow

​Pod Structure

​Container Details

​1. Agent Container

​2. Envoy Sidecar

​3. A2A Sidecar

​4. PID Mapper

​Shared Volumes

​Init Container

​Network Flow

Pod Structure

Container Details

1. Agent Container

2. Envoy Sidecar

3. A2A Sidecar

4. PID Mapper

Shared Volumes

Init Container

Network Flow