Agent Pod Architecture

Pod Structure

When you run hexr deploy, your agent becomes a Kubernetes Pod with three containers, or four when the agent sets a2a=True. There is no init container: the SDK is baked into the image at hexr build time.

Containers
Shared Volumes
Pod Manifest

Image build: SDK baked in

The SDK is installed into the image at hexr build time, from the wheel in .hexr/. Version match with the build is guaranteed because it is the same wheel, not a re-resolution at pod start. No init container, no shared volume.

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
  containers:
    - name: agent           # Your code (:8080), SDK baked into the image
    - name: envoy-sidecar   # mTLS proxy (:15001/:15006)
    - name: pid-mapper      # PID → SPIFFE mapper
    # - name: a2a-sidecar   # Agent comms (:8090) — only when a2a=True

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.

How the SDK gets into the pod

It is already there. hexr build downloads the hexr-sdk wheel into .hexr/ and the generated Dockerfile installs it into the image:

COPY hexr_sdk*.whl /tmp/
RUN pip install --no-cache-dir -r requirements.txt \
    && pip install --no-cache-dir /tmp/hexr_sdk*.whl

There is no init container and no shared site-packages volume. Baking the SDK in means the version in the pod is the exact wheel hexr build resolved, so it cannot drift between build and run, and a pod cannot fail to start because a package index is unreachable. That failure would otherwise land at scale-up time rather than at build time.

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

How the SDK gets into the pod

Network Flow

​Pod Structure

​Container Details

​1. Agent Container

​2. Envoy Sidecar

​3. A2A Sidecar

​4. PID Mapper

​Shared Volumes

​How the SDK gets into the pod

​Network Flow

Pod Structure

Container Details

1. Agent Container

2. Envoy Sidecar

3. A2A Sidecar

4. PID Mapper

Shared Volumes

How the SDK gets into the pod

Network Flow