Skip to content

Latest commit

 

History

History
68 lines (57 loc) · 3.8 KB

architecture.md

File metadata and controls

68 lines (57 loc) · 3.8 KB
title Architecture Hub
description How Zelkor components interact and the trust boundaries that protect your agent.
type explanation
sidebar_group Architecture
sidebar_order 1
audience human
edition all

Architecture Hub

High-level flow: You deploy an agent. It communicates strictly through governed model and tool gateways, emitting a trace.

Zelkor is the self-hosted agent runtime: bring the agent you already wrote — it cannot break out, reach unauthorized data or networks, its prompts are verified, budget controlled, and it is under observation; tenants stay isolated.

This hub maps the hops and boundaries that the runtime enforces.

---
config:
  theme: neutral
---
flowchart LR
  laptop[Your laptop / Client]
  subgraph cluster [Your cluster]
    model[Model]
    tools[Tools]
    agent[Your agent]
    trace[Run trace]
  end
  laptop -->|run| agent
  agent --> model
  agent --> tools
  agent --> trace
Loading

Zelkor vs a DIY agent stack

The DIY baseline is a raw Deployment per agent, LiteLLM or direct provider SDKs, and hand-written NetworkPolicies.

Concern DIY: what you build and keep working Typical DIY failure Zelkor CE (one Helm release)
Provider keys A Secret mounted into each agent pod A compromised agent or dependency reads the key Key stays on the AI Gateway; the agent gets a consumer key (Request Path)
Runaway cost Per-agent retry and loop limits in code A loop runs overnight against the provider Gateway request cap returns 429 before the provider
Generated code exec() in the agent container, or a separate sandbox you wire in Code runs on the node kernel next to the agent's credentials Separate gVisor worker pod with no network (Sandbox Isolation)
Egress NetworkPolicies per agent and per datastore One missing rule lets the agent reach the internet or Postgres Generated per agent by the chart; on in the production install (Network Boundaries)
Tools Credentials and tenant filters in each tool server The model chooses the tenant or scope One MCP gateway; scope from the signed tenant JWT (MCP Governance)
Traces OTel wiring per framework Tool and guardrail spans missing from the run One Langfuse trace per run (Run Trace)
Tenants Tenant checks in agent code One tenant reads another's thread or rows Enforced at the gateways (Tenant Isolation)

Deep Dives

Each page answers one specific architectural question about how traffic flows and where the trust boundaries lie:

Page Question
Request Path How a client call reaches the model
Network Boundaries Who may talk to whom inside the cluster
Sandbox Isolation Where generated code executes
MCP Governance How a tool call is isolated and authenticated
External and Third-Party MCP How Zelkor isolates and governs third-party SaaS and external MCP servers
Run Trace What one run looks like in Langfuse
North-South Exposure What is published to the internet versus ClusterIP
Envoy Graph Routing How Envoy routes incoming calls to the correct agent deployment
Drop-In Agent Contract How the runtime wraps and governs your agent (Intercept, Wrap, MCP)
Tenant Isolation How one tenant identity is applied on a run
Agent Datastores Stateful infrastructure (Postgres, Qdrant) and BYO options