What Halro is and its object model

Halro is a self-hosted LLM gateway delivered as one Go binary. It sits between applications and upstream model services and centralizes credentials, budgets, routing, redaction, audit, and usage accounting—without an external database, cache, CDN, or browser-stored secrets.

Model invocation chain

Credential → Provider → Deployment → Route → Project → Gateway Key

Model invocation chain

Object	Meaning
Credential	Upstream Provider secret, stored with AES-256-GCM encryption
Provider	One upstream access point bound to an immutable Provider Profile
Deployment	“What this model on this Provider can do”
Route	Maps a public alias to one or more Deployments
Project	Ownership unit for budget, rate limits, CIDR, Token Guard, and redaction policy
Gateway Key	Application credential prefixed with gw_

Applications see only a Gateway Key and a Route model alias. They do not know the upstream Provider, actual target ID, or Provider Credential—by design.

From v0.8.2, a Provider may select an Admin-managed Outbound Proxy. It is an optional egress path, not a business object in the chain. Proxy authentication is Vault-encrypted and failure never silently falls back to direct connection. A Route spanning proxied and direct Providers crosses egress trust boundaries and requires explicit fallback review.

Run Governance chain

Work Unit → Run → Request → Provider Attempt
     └──────────────────────────────→ Outcome

Run Governance chain

Object	Meaning	Authority
Work Unit	Work whose final business result should count once, such as a ticket or code repair	Accounting Ledger
Run	One execution of the Work Unit, containing multiple requests, retries, and fallback	Accounting Ledger
Request / Attempt	One client request and its one or more Provider calls	Accounting Ledger and derived Usage views
Outcome	Structured business result submitted by a trusted evaluator under the frozen Definition version	Governance Journal

One Work Unit can have multiple Runs. A failed first execution can close and restart in a new Run; the final result counts once, while unit-result cost includes every Attempt from every Run.

Halro does not orchestrate agents or decide business success. Before Provider I/O it enforces both Project and Run budget admission, preserves auditable cost attribution, and joins cost with Outcome by Work Unit at report time.

What happens after a request arrives

Client / SDK → protocol facade (OpenAI / Anthropic compatible)
             → authentication / policy / budget / redaction / accounting
             → capability-aware routing → versioned Provider Profile
             → SafeTransport → upstream

Two invariants matter: budget reservation is durable before an upstream request is sent, and once response bytes are visible to the client, Halro never silently switches Provider.

Continue with First Admin Console setup to build the first real chain.