Skip to main content
Hexr uses SPIFFE (Secure Production Identity Framework for Everyone) to give every agent process a unique, cryptographically verifiable identity. Unlike API keys or environment variables, a SPIFFE identity cannot be guessed, copied without detection, or used outside the context it was issued for. When your agent calls a cloud service or communicates with another agent, both sides verify each other’s identity through certificates — no tokens, no secrets shared in advance.

​
What is a SPIFFE ID?

A SPIFFE ID is a URI that uniquely identifies a workload. In Hexr, it identifies a specific agent process:
PartExampleDescription
Trust domainhexr.cloudYour SPIRE trust domain
TypeagentAlways agent for Hexr workloads
Tenantacme-corpYour tenant namespace
Agent nameresearch-analystFrom @hexr_agent(name=...)
RoleresearcherSub-agent process role
Full example: 
spiffe://hexr.cloud/agent/acme-corp/research-analyst/researcher

​
What is an SVID?

An SVID (SPIFFE Verifiable Identity Document) is the cryptographic proof of a SPIFFE ID. Hexr uses two types, each serving a different purpose:
TypeFormatUsed for
X.509 SVIDX.509 certificate + private keymTLS between services — Envoy loads this automatically
JWT-SVIDSigned JWT tokenCloud credential exchange — presented to AWS STS, GCP WIF, Azure

​
Per-process identity

Hexr’s key innovation is assigning a distinct SPIFFE ID to each process within an agent container — not just the pod. If you run a multi-agent framework with a researcher, writer, and editor, each role gets its own identity: 
Pod: content-crew (tenant: acme-corp)
├── PID 1  (main)       → spiffe://hexr.cloud/agent/acme-corp/content-crew/main
├── PID 42 (researcher) → spiffe://hexr.cloud/agent/acme-corp/content-crew/researcher
├── PID 43 (writer)     → spiffe://hexr.cloud/agent/acme-corp/content-crew/writer
└── PID 44 (editor)     → spiffe://hexr.cloud/agent/acme-corp/content-crew/editor
This enables:
  • Per-role cloud access — the researcher can access BigQuery but not S3
  • Per-role cost tracking — attribute LLM costs exactly to each role
  • Per-role audit logs — know precisely which sub-agent performed each action

​
Identity lifecycle

From the moment you run hexr build to the moment your agent calls a cloud API, here’s how your SPIFFE identity is established:

Build: AST discovery

hexr build scans your Python source via AST analysis. It discovers all agent roles — researcher, writer, editor — and generates process context JSON files that describe each role’s identity and resource requirements.

Pod starts: SDK installed

An init container installs the Hexr SDK from the private PyPI registry into a shared volume, ensuring the version matches what was used during hexr build.

PID Mapper: process registration

When your agent process starts — for example, the “researcher” role on PID 42 — the PID Mapper reads /proc, maps the container PID to the host PID, and writes enriched context JSON for SPIRE workload attestation.

SPIRE: SVID issued

The Auto-Registrar creates a SPIRE entry. SPIRE issues an X.509-SVID with a 5-minute TTL that auto-renews at 50% TTL. The certificate’s subject URI is the per-process SPIFFE ID.

Runtime: mTLS and cloud access

Your agent uses the X.509-SVID for mTLS (via Envoy) and presents its JWT-SVID to cloud providers — AWS STS, GCP Workload Identity Federation, Azure — for short-lived credential exchange.

​
Trust domain

Your SPIFFE trust domain depends on your deployment model:
DeploymentTrust domain
Hexr Cloudhexr.cloud
Self-hosted (default)demo.hexr.dev
Custom self-hostedConfigurable via Helm

​
Certificate rotation

SVIDs are short-lived and rotate automatically — you never manage certificate renewal yourself:
CertificateTTLRotation
X.509 SVID5 minutesSPIRE auto-renews at 50% TTL
JWT-SVID5 minutesIssued on-demand for each STS exchange
CA certificate24 hoursSPIRE Server rotates automatically
Because SVIDs rotate every 5 minutes, even if a certificate were somehow extracted from a running process, it would be valid for at most a few minutes before becoming useless.