Deployment Topology

How Hoziron deploys in production — container structure, networking, storage, and scaling.

Single-Node Architecture

Hoziron is a single-process, single-node platform. All components run within one binary:

Container Deployment

Container Details

Property	Value
Base image	`gcr.io/distroless/cc-debian12:nonroot`
User	UID 65532 (nonroot)
Entrypoint	`hoziron start --listen 0.0.0.0:4200`
Port	4200 (API + metrics on same port)
Volume	`/data` (all persistent state)
Read-only filesystem	Yes (except /data)
Health probe	`GET /health`

Environment Variables

Variable	Purpose	Container Default
`HOZIRON_HOME`	Data directory	`/data`
`HOZIRON_LISTEN`	Listen address	`0.0.0.0:4200`
`HOZIRON_LOG`	Log filter	`info`
`HOZIRON_LOG_FORMAT`	Log format	`text` (recommend `json` for production)
`ANTHROPIC_API_KEY`	Provider key	— (inject from secrets)

Network Topology

Kubernetes

Bare Metal / VM

For bare metal, enable native TLS if no reverse proxy:

[server.tls]
enabled = true
cert_path = "/opt/hoziron/tls/cert.pem"
key_path = "/opt/hoziron/tls/key.pem"

Storage Layout

/data/                          (HOZIRON_HOME in containers)
├── config.toml                 Platform configuration
├── .env                        API keys (local dev only)
├── daemon.json                 Runtime connection info
├── hoziron.db                  Main SQLite database
├── packages.lock               Dependency lockfile
├── data/
│   ├── memory/                 Per-agent KV stores
│   └── sessions/               Conversation histories
├── auth.db                     API key store (mode 0600)
├── audit.db                    Audit trail (WAL mode)
├── packages/                   Installed catalog packages
│   ├── claims-intake/
│   ├── document-ocr/
│   └── installed.json          Installation metadata
├── keys/                       Signing keypair
│   └── default.key             Ed25519 private key (mode 0600)
├── vault/                      Encrypted credentials
└── agents/                     Auto-load manifest directory
    ├── claims-processor.toml
    └── monitor-agent.toml

Storage Sizing

Component	Growth Pattern	Typical Size
`hoziron.db`	Per-agent, per-session	10 MB – 1 GB
`data/memory/`	Per-agent, per-message	1 MB per 1000 messages
`audit.db`	Per-API-request	~100 bytes/entry, 100K entries max
`packages/`	Per-install	10 KB – 5 MB per package
`auth.db`	Per-key	< 1 MB

Scaling Considerations

Vertical Scaling (Recommended)

Hoziron is single-node by design. Scale by increasing resources:

Dimension	Scale Factor
More agents	More memory (10 MB base per agent)
More concurrent requests	More CPU cores (tokio async)
Longer history	More disk (session storage)
More integrations	More file descriptors (MCP processes)

Horizontal Isolation

For multi-team environments, run separate instances:

Each instance has:

Its own config, agents, competencies, and data
Shared registry access (install same packages)
Shared IdP (same SSO, different role mappings)
Shared LLM providers (separate API keys if needed)

High Availability

Hoziron does not natively support active-active HA (single-process, SQLite). For high availability:

Approach	How	Trade-offs
Kubernetes restart	`restartPolicy: Always` + health probes	Seconds of downtime on crash
PDB + rolling update	`PodDisruptionBudget` with 1 replica	Controlled maintenance windows
Warm standby	Second instance with shared PVC (active-passive)	Manual failover
Stateless agents	Recreate from manifests on new instance	Lose in-flight sessions

For most enterprise deployments, Kubernetes auto-restart with graceful shutdown (30s termination grace) provides sufficient availability.

Graceful Shutdown

Set terminationGracePeriodSeconds >= 30 in Kubernetes to allow the flush to complete.