hexr build

A verified first run

Everything below is a real run from a clean uv virtualenv with no pip installed, against the published SDK. It is what you should see.

uv venv .venv
uv pip install 'hexr-sdk[cli]'
hexr build agent.py --tenant acme --target development

📦 No pip in this environment; bootstrapping it with ensurepip...
📦 Downloading hexr-sdk==0.5.31 (manylinux_x86_64) from https://pypi.org/simple/...
✅ Downloaded hexr-sdk wheel for Docker image build
✅ Build completed successfully!
📦 Image: acme/agent:development
📂 Artifacts: .hexr
⏱️  Duration: 2.1s

Artifacts produced in .hexr/:

Dockerfile
agent.py
build-summary.json
enterprise_pid_mapper.py
hexr_sdk-0.5.31-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
manifests/
  agent-pod.yaml
  agent-envoy-sidecar-config.yaml
  namespace.yaml
  network-policy.yaml
  rbac.yaml
  resource-quota.yaml
requirements.txt

One warning is expected off-cluster. hexr build on a laptop logs Could not get enterprise host PID ... Using fallback simulation. PID mapping needs a pod with hostPID: true; there isn’t one on your machine, the build falls back cleanly, and the manifests are unaffected.

Three things fixed in 0.5.31, in case you are on an older SDK

Symptom	Cause
Authentication failure fetching the SDK wheel	Older builds defaulted to the private index. `hexr-sdk` is on public PyPI; 0.5.31 defaults there
`No module named pip`	`uv` virtualenvs have no pip. 0.5.31 bootstraps it with `ensurepip`
The image ships an SDK older than the one you are running	The local-`dist/` shortcut took any wheel it found, with no version check. 0.5.31 pins the glob to the running version and reports what it skipped

The third one is worth knowing about if you built images before 0.5.31: check which wheel is in your .hexr/ directory against python -c "import hexr; print(hexr.__version__)". If they differ, rebuild.

Usage

hexr build <agent_file> --tenant <tenant> [options]

Arguments

path

required

Path to your Python agent file.

hexr build my_agent.py --tenant acme-corp
hexr build agents/content_crew.py --tenant acme-corp

Hexr Cloud changes five defaults

hexr build behaves differently once you have run hexr login. This is worth knowing before you compare output with a colleague, because the same command can bake a different image on two machines. The cloud defaults apply only when both of these hold:

A saved cloud config is authenticated against a hexr.cloud URL, and
you passed neither --registry nor --pypi-url.

When they do, five values change:

Flag	Default without login	Default when logged in
`--registry`	none, image is tagged locally	`us-central1-docker.pkg.dev/hexr-cloud-prod/hexr-images`
`--pypi-url`	`https://pypi.org/simple/`	`https://pypi.hexr.cloud/simple/`
`--trust-domain`	`demo.hexr.dev`	`hexr.cloud`
`--mock-mode` / `--no-mock-mode`	on	off
`--gcp-service-account`	none	`hexr-pypi-reader@hexr-cloud-prod.iam.gserviceaccount.com`

They move as a set on purpose. The private index is only reachable through the Workload Identity binding that the service account provides, so taking the index without the binding would give you an image that cannot install its own SDK. The practical consequence: passing --registry alone also turns off the private index, the cloud trust domain and the service account binding. If you want your own registry but the rest of the cloud defaults, pass them explicitly.

Options

string

required

Tenant identifier. Maps to Kubernetes namespace tenant-{tenant}.

string

Override the agent name (default: extracted from @hexr_agent(name=...) or filename).

string

default:"development"

Target environment: development, staging, or production.Affects OPA policies, resource limits, and security scanning levels.

string

Container registry base URL.

hexr build agent.py -t acme --registry us-central1-docker.pkg.dev/my-project/images

No default when you are not logged into Hexr Cloud; the image is tagged locally. When you are logged in and pass neither --registry nor --pypi-url, it defaults to us-central1-docker.pkg.dev/hexr-cloud-prod/hexr-images.

string

Index to download the hexr-sdk wheel from when baking the image.The default depends on whether you are logged into Hexr Cloud:

Situation	Default index
Not logged in (the normal case)	`https://pypi.org/simple/`
Logged into Hexr Cloud, and you passed neither `--pypi-url` nor `--registry`	`https://pypi.hexr.cloud/simple/`

Passing either --pypi-url or --registry explicitly turns the whole set of cloud defaults off, including the registry and the Workload Identity service account binding. They move together on purpose: the private index is only reachable through that binding.

Before 0.5.31 this flag defaulted to the private index in every case, so hexr build failed for anyone without Hexr Cloud access. See A verified first run above.

string

default:"3.11"

Python version for the container.

string

default:"python:3.11-slim"

Base Docker image.

string

Comma-separated cloud providers for credential exchange.

hexr build agent.py -t acme --multi-cloud aws,gcp,azure

flag

Enable subprocess role management for multi-process agents.

flag

Enable security scanning during build (dependency audit).

path

default:".hexr"

Output directory for generated artifacts.

flag

Generate manifests only — skip container image build.

flag

Show what would be generated without creating files.

string

default:"demo.hexr.dev"

SPIFFE trust domain for identity generation.Logged into Hexr Cloud, and left unset, this becomes hexr.cloud.

What Gets Generated

.hexr/
├── Dockerfile                    # Multi-stage build with SDK injection
├── requirements.txt              # Auto-detected from imports
├── agent-pod.yaml                # Pod spec with 4 containers
├── namespace.yaml                # tenant-{name} namespace
├── rbac.yaml                     # ServiceAccount + RoleBindings
├── agent-card.yaml               # ConfigMap for A2A discovery
├── process-contexts/             # Per-process SPIFFE context
│   ├── researcher.json
│   ├── writer.json
│   └── editor.json
└── hexr-manifest.json            # Build metadata

AST Analysis

The build command performs ~2,900 lines of AST analysis to:

Detect the framework — CrewAI, LangChain, AutoGen, Strands, Swarm, or pure Python
Discover agents — Find all @hexr_agent decorators and framework-specific agent declarations
Map sub-agents — Identify roles (researcher, writer, editor) for per-process identity
Infer resources — Detect hexr_tool() calls to determine required cloud permissions
Detect A2A — Find A2AClient usage and a2a=True parameters
Build coordination graph — NetworkX analysis of agent relationships

Examples

Basic Agent

$ hexr build research_agent.py --tenant acme-corp

Analyzing research_agent.py...
  Framework: pure_python
  Agents: 1 (research-agent)
  Resources: aws_s3
  A2A: disabled

Generated .hexr/ (5 files)

CrewAI with A2A

$ hexr build content_crew.py --tenant acme-corp --multi-cloud aws,gcp

Analyzing content_crew.py...
  Framework: crewai
  Agents: 3 (researcher, writer, editor)
  Resources: aws_s3, gcp_bigquery
  A2A: enabled
  Subprocess support: auto-detected

Generated .hexr/ (8 files, 3 process contexts)

Production Build

$ hexr build agent.py -t acme --target production --security-scan \
    --registry us-central1-docker.pkg.dev/hexr-prod/images \
    --trust-domain hexr.cloud

CLI Overview

Commands

A verified first run

Three things fixed in 0.5.31, in case you are on an older SDK

Usage

Arguments

Hexr Cloud changes five defaults

Options

What Gets Generated

AST Analysis

Examples

Basic Agent

CrewAI with A2A

Production Build

​A verified first run

​Three things fixed in 0.5.31, in case you are on an older SDK

​Usage

​Arguments

​Hexr Cloud changes five defaults

​Options

​What Gets Generated

​AST Analysis

​Examples

​Basic Agent

​CrewAI with A2A

​Production Build

A verified first run

Three things fixed in 0.5.31, in case you are on an older SDK

Usage

Arguments

Hexr Cloud changes five defaults

Options

What Gets Generated

AST Analysis

Examples

Basic Agent

CrewAI with A2A

Production Build