Trussium¶

Cloud-native runtime for AI applications¶

Trussium is a provider-neutral runtime for operating AI capabilities across hosted providers and private models. It gives applications one HTTP API and one operational contract while allowing providers, models, and deployment environments to change independently.

The runtime is designed for teams that need normalized capability responses, request correlation, streaming support, health and readiness checks, metrics, tracing, structured logs, and bounded shutdown behavior.

Trussium architecture overview

Conceptual architecture: provider logos represent adapter examples; the runtime does not install or require every provider shown.

Deployment and request flows¶

Choose the deployment model that matches your operating needs:

Trussium deployment paths

Every integration follows the same provider-neutral request lifecycle:

Trussium request lifecycle

Project components¶

Runtime¶

The Trussium runtime provides the core execution platform, including capability contracts, provider integration, health endpoints, metrics, tracing, and structured operational logging.

Kubernetes Operator¶

The Trussium Operator manages TrussiumRuntime resources through a Kubernetes-native reconciliation loop, including runtime configuration, deployment lifecycle, status, events, and upgrades.

Helm chart¶

The official Helm chart packages the runtime for configurable Kubernetes installation, upgrade, and operational deployment.

The chart installs the runtime workload. It does not install the Kubernetes Operator; the Operator is a separate project for teams that want TrussiumRuntime custom resources and reconciliation.

trussiumctl CLI¶

The trussiumctl CLI is a standalone Go binary for read-only inspection and guarded Kubernetes and Helm operations. It discovers deployed component versions for diagnostics and upgrade preflights, requires explicit confirmation for mutations, validates manifests server-side, and verifies completed operations.

Knowledge Agent reference application¶

The Trussium Knowledge Agent is a Python reference application for Markdown knowledge search and documentation maintenance. It can index explicitly selected local Markdown repositories and manually refresh bounded snapshots of selected public GitHub repositories pinned to full commit SHAs. It sends chunks to a configured Trussium runtime for embeddings and runs bounded semantic search over pgvector. Public GitHub indexing remains tokenless and explicit. An opt-in private GitHub App connector is also available for self-hosted deployments: the installer selects repositories, each access token is scoped to one repository, and security events plus expiring authorization leases restrict retrieval after access changes. Private sources require operator-managed credentials and HTTPS webhook configuration; the feature is not enabled by default. Webhooks never trigger content indexing, and automatic content synchronization is unsupported. See the canonical private-source operations guide, private-access ADR, and public GitHub refresh guide. Its ask command sends retrieved passages to a configured Trussium chat model and returns an answer only when its citation IDs map to retrieved source paths and headings; missing or invalid evidence produces an insufficient-evidence response. A browser interface is available as a local reference UI. The bounded documentation-audit workflow implementation is now merged across the runtime, Python SDK, and Knowledge Agent; availability in published component releases may differ. See the public agent workflow guide for composition and release guidance, and the repository roadmap for current status and the canonical setup instructions. The repository also includes a small retrieval-evaluation corpus and an evaluate CLI command that reports Hit@k, Recall@k, MRR@k, and expected versus retrieved source citations. These metrics assess retrieval and citation coverage only; they do not prove that a generated answer is factually correct. See the evaluation guide for setup and interpretation. The app also provides a local browser interface that displays citation-validated answers, source paths and headings, and a clear insufficient-evidence state. It is a reference UI, not an authenticated multi-user service; see the browser-interface guide for its API, setup, and deployment boundary. Its source lifecycle safeguards keep deletions and confirmed GitHub access loss from being undone by a restored PostgreSQL backup: operators must reconcile the separately stored lifecycle journal before exposing a restored database. The repository records a successful rehearsal in a disposable local PostgreSQL cluster; it does not validate a deployment's backup storage, credentials, or access controls. For details, see the canonical restore procedure and lifecycle decision. For the app-plus-PostgreSQL Docker Compose path, see the Knowledge Agent deployment guide; it is self-hosted and does not require private GitHub credentials for local or public-source use.

Choose a starting point¶

Use the Task guides section in the navigation for a direct path through a common workflow. The links below provide the same entry points with context:

Run locally: start with the runtime CLI and API usage guides.
Run privately: follow self-hosting, then review provider configuration.
Deploy to Kubernetes: use the Helm chart for a direct runtime deployment, or the Operator overview for reconciled custom resources.
Operate in production: review health and readiness, metrics, tracing, and shutdown behavior.

Current release baseline¶

The public components are independently versioned. The current baseline is:

The runtime, chart, operator, and CLI remain independently versioned components; SDKs and provider adapters are optional integrations. The runtime’s bounded MCP tool-execution surface, including the bounded ping handshake, declared tool input schemas, cursor pagination, lifecycle notifications, and explicit tool success status, is included in the v1.27 release line and is documented in the Runtime capabilities section.

The Operator compatibility matrix records runtime v1.27.0, v1.29.1, and v1.30.0 as tested with Operator v1.0.5. Runtime v1.30.0 was validated through the operator's Kind lifecycle, upgrade, and rollback checks; the runtime release baseline does not imply compatibility with other operator or chart versions. Runtime Helm chart v1.3.1 still defaults to runtime 1.27.0; the Operator uses explicit image overrides, so the chart default has not changed.

Project status¶

The public roadmap and architecture decisions describe the supported contracts and their maturity. Start with the runtime roadmap, then consult the relevant component's release and compatibility guidance before upgrading.

Documentation¶

Use the navigation to access runtime, operator, Helm, and CLI documentation. Each section covers public contracts, deployment guidance, operational behavior, and architecture decisions. Contributions and documentation corrections are welcome through the contributing guide.