Architecture

For the full technical ASCII diagram and desktop wire-up details, see the Architecture overview. This page is the conceptual entry point.

Two layers

AKOS is not written from scratch. It stands on AgentsKit — a permissively-licensed (MIT) open-source agent runtime.

┌─────────────────────────────────────────────────────────┐
│  AKOS — the OS layer (this repo)                        │
│  Governance · audit · RBAC · visual flow editor ·       │
│  processes · verticals · white-label · multi-tenant ·   │
│  marketplace · desktop app                              │
│  Packages named  os-*                                   │
└────────────────────────┬────────────────────────────────┘
                         │ peerDependency
┌────────────────────────┴────────────────────────────────┐
│  AgentsKit — open-source upstream (MIT)                 │
│  LLM adapters · reasoning & durable runtime ·           │
│  memory backends · tools · skills · RAG primitives ·    │
│  sandbox · evaluation                                   │
│  Packages named  @agentskit/*                           │
└─────────────────────────────────────────────────────────┘

Rule of thumb: a package starting os- lives in this repo; one starting @agentskit/ comes from upstream. The hard rule (ADR-0002): never re-implement an upstream primitive — depend on it. Every community improvement to AgentsKit flows into AKOS for free.

Five layers, 50+ packages

The codebase is stacked. Each layer may only depend on layers below it — never sideways, never upward. A CI gate (check:layers) enforces this on every commit. If someone wires a lower layer to a higher one, the build fails.

os-core is the hub: it defines every typed schema used across the monorepo, is consumed by 60+ packages, and is kept under 25 KB gzipped with zero LLM or UI dependencies (ADR-0013).

The four design principles

These principles shape every line of code and are documented in full in Philosophy.

Contract-first

A Zod schema validates every boundary — every HTTP call, every JSON-RPC message, every file read. Bad data is rejected at the door. If a contract changes unexpectedly, the build fails. You can trust the types: if the code declares a value is a FlowConfig, it was parsed at the boundary and really is one.

Governed by design

A signed audit ledger, role-based access, sandboxing, an egress allowlist, and human-approval gates live inside the runtime — not bolted on as an afterthought. The dispatcher enforces RBAC on every RPC handler before the handler runs. There is no back door.

Hexagonal / port-first

50+ packages, each structured as a port (interface) + a swappable binding (implementation). Postgres, S3, Vercel Sandbox, Vault, Resend — each is a binding you can replace. A vendor-isolation CI gate (check:vendor-isolation) blocks leakage at commit time. No lock-in by construction.

Decisions are documented

Every architectural choice is an Architecture Decision Record (ADR). 98+ ADRs are on file. Changing the architecture requires writing an ADR first. Nothing is folklore.

The request path

Every action — a click, a webhook, an agent calling a tool — becomes one typed RPC call and takes the same governed path:

Caller (UI / webhook / agent)
    ↓
Schema parse       ← Zod validates input
    ↓
Capability check   ← RBAC: may caller do this?
    ↓
Handler runs       ← the actual logic
    ↓
Audit + respond    ← logged to ledger; typed result returned

321 handler entries. 0 unmarked stubs. All reachable over both stdio and HTTP transport (parity matrix CI-verified).

Deployment modes

The same sidecar ships in three modes using the same typed protocol:

Same flow, same agent, same governance — on a laptop, in a browser, or in a Kubernetes pod.

Where to go deeper

• Architecture overview — full ASCII diagram and package wiring.
• Hexagonal architecture — port/binding pattern explained.
• Principal & RBAC — how identity, roles, and capability checks work.
• Distribution tiers — local vs. cloud vs. hosted.
• ADRs — the 98+ decision records behind every choice.