openbox-core

Purpose

openbox-core is the data-plane orchestration service for OpenBox agents. It runs a single pod with 5 sibling containers that share lifecycle and localhost: an HTTP API server, three Temporal SDK workers (governance / attestation / observability), and a cron scheduler. All agent workflow execution flows through this pod.

Plane: Data plane.

Ports & endpoints

Port	Protocol	Purpose	Exposed via
8086	HTTP/REST	Core API (called by backend + external)	Istio Gateway
—	gRPC → external	Temporal SDK worker traffic	Cluster-internal (no exposed port)

Sibling openbox-core-codec runs as a separate rollout (not part of the 5-container pod):

• Port 8443 HTTPS · Path /codec/api — payload codec for Temporal Web UI

Runtime

Pod topology — 5 containers per pod:

Container	Purpose	Notes
openbox-core-service-server	HTTP API :8086	Public REST endpoints
openbox-core-service-governance-worker	Temporal SDK	Governance-workflow task queue
openbox-core-service-attestation-worker	Temporal SDK	Cryptographic attestation workflows
openbox-core-service-observability-worker	Temporal SDK	Observability + audit-log workflows
openbox-core-service-scheduler	cron	Scheduled workflow launcher

All 5 share pod lifecycle, filesystem, and localhost — a pod restart kills all 5.

Property	Value (per-container)	Value (per-pod total)
Resource requests	200m CPU / 500 Mi RAM	1 vCPU / 2.5 Gi RAM
Resource limits	1 vCPU / 2 Gi RAM	5 vCPU / 10 Gi RAM
HPA min → max pods	1 → 5 (target CPU 70%)	—
Node placement	General-purpose CPU pool	—

Scaling pods 1 → 5 gives you 5 → 25 container instances total.

Configuration

Chart values keys (top-level openbox-core.*)

Authoritative reference: values-reference. Most-configured keys:

Key	Purpose
image.repository / image.tag	Container image (shared by all 5 containers)
autoscaling.*	Pod-level HPA (scales all 5 containers together)
resources	Per-container resources — total pod = sum of 5
redis.external.host / .port	ElastiCache / Memorystore endpoint (overrides in-cluster Redis)
temporal.mode	cloud or self-hosted — see Temporal variants
temporal.cloud.namespace / .address / .tlsSecretRef	Temporal Cloud connection details
temporal.server.replicas	Self-hosted Temporal server pod count (default 4)
serviceAccount.annotations	IRSA for KMS access

Runtime env vars

• TEMPORAL_ADDRESS — Temporal frontend gRPC endpoint (Cloud or self-hosted)
• TEMPORAL_NAMESPACE — from temporal.cloud.namespace OR default openbox
• REDIS_URL — Redis connection string
• KMS_KEY_ARN — from values (envelope encryption)
• OPA_URL, GUARDRAILS_URL, KEYCLOAK_URL — inter-service endpoints

IRSA / IAM permissions required (AWS)

Same subset as openbox-backend for KMS (Encrypt/Decrypt/GenerateDataKey/DescribeKey). No S3 permissions needed (only backend touches OPA bundles).

Dependencies

Downstream

Target	Protocol	Purpose
temporal-frontend	gRPC :7233	Workflow start/signal/query (workers + scheduler)
openbox-backend	HTTP/REST	Auth check, user context
opa-app	HTTP/JSON :8181	Authorization on agent operations
guardrails-api	HTTP/REST :8000	ML content filter for agent I/O
llamafirewall-server	HTTP/REST :8000	Deep prompt-injection detection
openbox-core-redis	Redis TCP :6379	Session/state cache
openbox-postgresql	JDBC :5432	Persistent agent state
AWS KMS	HTTPS AWS API	Envelope encryption

Upstream

• Istio Gateway (via ingress) — external clients
• openbox-backend (cluster-internal) — for orchestration triggers

Deployment guidelines

Prod

• Never disable any of the 5 containers — the chart treats them as one atomic pod. Disabling one silently breaks workflows.
• autoscaling.maxReplicas: 5+ typical. Beyond 10, review Temporal task-queue backpressure first.
• Pin image.tag — all 5 containers share the tag.
• Use Temporal Cloud OR self-hosted (see Temporal variants); pick before install — migration mid-flight requires a maintenance window.

Local PoC

• autoscaling.minReplicas: 1, maxReplicas: 1 — laptop can't afford 5 pods × 5 containers = 25 instances
• Use in-cluster Redis (Bitnami)
• Temporal mode: cloud if you have creds, else self-hosted with replicas: 1 (still 4 Temporal server pods but low resource limits)

Troubleshooting

Only 1 of 5 containers Ready, others CrashLoopBackOff → Temporal frontend unreachable. Workers can't connect. Check TEMPORAL_ADDRESS env var + Temporal frontend Service kubectl get svc -n temporal.

Pod stuck in Pending → Not enough node CPU. 5 vCPU limit per pod is heavy — check kubectl describe pod for Insufficient cpu events. Scale node group up OR reduce resources.limits.

Scheduler container idle — no workflows firing → Cron schedule config missing. Check kubectl logs deploy/openbox-core -c openbox-core-service-scheduler — should show Scheduler started with N cron jobs. If N=0, values-side scheduler config is empty.

Workflow starts but never completes → Worker container for the target queue is failing / lagging. kubectl logs deploy/openbox-core -c openbox-core-service-governance-worker --tail 50 and grep for errors. Task queue backpressure = need more pods (HPA up).

Guardrails-api errors flood logs → Downstream guardrails-api down or llamafirewall GPU unhealthy. Core does not fail-closed by default — agent runs continue with degraded safety. Fix guardrails-api first, then this stops.