Underpass Runtime

Governed execution plane for event-driven AI agents.

We don't build models. We build the infrastructure that makes them actually work. A 7B model with 394 tokens of surgical context outperforms a frontier model drowning in 6,000 tokens of noise.

What it does

Underpass Runtime gives AI agents isolated workspaces with 99 governed tools — filesystem, git, build, test, security scans, containers, Kubernetes — all under policy enforcement with full telemetry.

When an event fires (task assigned, PR opened, build broken), a specialized agent activates, gets only the context it needs, selects the best tools via Thompson Sampling, and executes them in a governed workspace. The telemetry feeds back into the learning loop. No polling. No orchestrator.

NATS event → agent activates → session created →
  tools selected (Thompson Sampling) → executed in isolated workspace →
    telemetry recorded → policies improve → next event, better decisions

Architecture

                    ┌─────────────────────────────────┐
  NATS event ──────>│         Agent (specialized)      │
                    └──────────────┬──────────────────┘
                                   │ HTTPS/TLS
                    ┌──────────────▼──────────────────┐
                    │      Underpass Runtime           │
                    │                                  │
                    │  Sessions ──── Tool Catalog      │
                    │  Policy ────── Invocation Engine  │
                    │  Artifacts ─── Telemetry          │
                    └──┬────────┬────────┬────────┬───┘
                       │        │        │        │
                    Valkey    NATS    S3/MinIO   OTLP
                  (state)  (events) (artifacts) (traces)

Full TLS across all 5 transports. Helm chart with mTLS support and fail-fast validation.

Proven in production-style E2E

15 E2E tests run as Kubernetes Jobs against a live cluster with TLS enabled:

Test	What it proves
Multi-agent pipeline	5 agents (architect → developer → test → review → QA) implement an HTTP retry middleware in Go. 14 tool invocations, 10 NATS events, 6 real artifacts
Event-driven agent	NATS event triggers code-review agent. Writes Go code with a known bug, analyzes it, produces review with 3 findings. Full NATS round-trip
Full infra stack	TLS + Valkey persistence + NATS events + outbox relay + S3 artifacts — all working together
LLM agent loop	OpenAI gpt-4o-mini drives tool discovery + invocation over HTTPS. Creates a Go project in 5 iterations

See e2e/README.md for full evidence.

Quick start

# Run locally (memory backends, no infra needed)
go run ./cmd/workspace

# Health check
curl http://localhost:50053/healthz

# Create a session and invoke a tool
curl -X POST http://localhost:50053/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"principal":{"tenant_id":"dev","actor_id":"me","roles":["developer"]}}'

# Deploy with Helm (TLS + Valkey + NATS)
helm install underpass-runtime charts/underpass-runtime \
  --set stores.backend=valkey \
  --set valkey.enabled=true \
  --set eventBus.type=nats \
  --set tls.mode=server \
  --set tls.existingSecret=my-tls-secret

Tool catalog

99 capabilities across 23 families:

Family	Count	Examples
fs.*	10	read, write, search, patch, stat, copy, move, delete
git.*	11	status, diff, commit, push, log, branch, checkout, apply_patch
repo.*	14	detect, build, test, coverage, symbols, static_analysis, package
k8s.*	8	get_pods, apply_manifest, rollout, logs, services, deployments
redis.*	7	get, set, del, scan, mget, exists, ttl
node.*	5	build, install, lint, test, typecheck
container.*	4	run, exec, logs, ps
go.*	4	build, test, generate, mod.tidy
rust.*	4	build, test, clippy, format
security.*	4	scan_dependencies, scan_secrets, scan_container, license_check
artifact.*	3	upload, download, list
image.*	3	build, push, inspect
kafka.*	3	produce, consume, topic_metadata
nats.*	3	publish, request, subscribe_pull
python.*	3	test, install_deps, validate
rabbit.*	3	publish, consume, queue_info
c.*	2	build, test
conn.*	2	list_profiles, describe_profile
mongo.*	2	find, aggregate
api.*	1	benchmark
ci.*	1	run_pipeline
quality.*	1	gate
sbom.*	1	generate

Each tool carries metadata: scope, side_effects, risk_level, requires_approval, idempotency, cost_hint.

API

Method	Endpoint	Description
GET	/healthz	Health check
GET	/metrics	Prometheus metrics
POST	/v1/sessions	Create workspace session
DELETE	/v1/sessions/{id}	Close session
GET	/v1/sessions/{id}/tools	List tools
GET	/v1/sessions/{id}/tools/discovery	Discover tools (filtered)
GET	/v1/sessions/{id}/tools/recommendations	Tool recommendations
POST	/v1/sessions/{id}/tools/{name}/invoke	Invoke tool
GET	/v1/invocations/{id}	Get invocation
GET	/v1/invocations/{id}/logs	Get logs
GET	/v1/invocations/{id}/artifacts	List artifacts

Part of Underpass AI

Repository	What it does
underpass-runtime (this)	Governed tool execution + telemetry + tool-learning
rehydration-kernel	Surgical context materialization from knowledge graphs
swe-ai-fleet	Multi-agent SWE platform — planning, deliberation, execution
underpass-demo	See it all working together

Documentation

• Configuration Reference — 80+ environment variables
• TLS Deployment Guide — step-by-step for all 5 transports
• E2E Test Evidence — cluster validation with logs and evidence JSON

License

Apache License 2.0 — see LICENSE.

Created by Tirso Garcia · LinkedIn · Underpass AI