# vikasprogrammer/agent-os architecture

> Architecture diagram of the GitHub repository vikasprogrammer/agent-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikasprogrammer/agent-os
- Repository: https://github.com/vikasprogrammer/agent-os

## Overview

#### Purpose and Entry Points
Agent OS is a Node.js control plane for safely running autonomous agents across isolated workspaces/tenants. Its defining invariant is that external side effects traverse a governed gateway.

Primary boot paths are CLI/server startup in `src/index.ts`, command handling in `src/cli.ts`, and composition/loading in `src/kernel.ts`. `npm run serve` exposes the API, console, and terminal proxy; `src/demo.ts` runs deterministic governance scenarios.

#### Kernel, Runs, and Agent Loading
The kernel assembles a tenant-scoped runtime: agents, policy, state, gateway, runtime adapters, connectors, and observability. Data-home resolution separates open-source software from private tenant data and establishes per-workspace storage boundaries.

- `src/kernel.ts`
- `src/core/orchestrator.ts`
- `src/core/run.ts`
- `src/home.ts`

A run is created from an agent/task, driven by a runtime adapter, and transitions through execution, approval waits, completion, or failure. Bundled agent manifests under `config/agents/*/agent.json` are seeds; tenant-home agents override matching IDs.

#### Governed Effect Gateway
`src/gateway/gateway.ts` is the architectural chokepoint for every registered capability invocation. Its pipeline classifies policy risk, obtains approval when required, reserves/debits budget, resolves acting identity, deduplicates retries, invokes the effect, and appends audit events.

- `src/gateway/gateway.ts`
- `src/gateway/idempotency.ts`
- `src/capabilities/registry.ts`
- `src/capabilities/normalize.ts`

Capabilities are the plugin boundary for external actions. Connector implementations and agent/runtime code should request effects through this boundary rather than invoke vendors directly.

#### Governance and Trust Plane
Governance supplies enforceable controls around the gateway: data-driven rules, human approval queues, cost/token caps, principal and recipient checks, append-only audit, semantic/file guards, and policy revision/reconciliation.

- `src/governance/policy.ts`
- `src/governance/approvals.ts`
- `src/governance/budget.ts`
- `src/governance/audit.ts`
- `src/governance/identity.ts`

Default and demo risk rules are externalized in `config/policy/default.policy.json` and `config/policy/demo.policy.json`. Policy classifies effects as green, yellow, red, or denied; yellow/red suspend the run until an authorized decision is recorded.

#### State, Memory, and Tenant Isolation
Persistent workspace state is centered on SQLite, with stores for members/auth, agents, tasks, goals, knowledge, artifacts, runtime accounts, policy revisions, and session activity. Audit JSONL remains the durable per-run system of record and is mirrored into state for console/API use.

- `src/state/db.ts`
- `src/state/control.ts`
- `src/memory/index.ts`
- `src/tenant-registry.ts`

A process-per-tenant deployment isolates by data home and DB. The optional registry mode constructs separate runtimes per tenant and routes by subdomain or trusted tenant header.

#### Runtime, Sessions, and External Boundaries
Agents run through mock or Claude Code adapters. Claude sessions are launched in agent folders through tmux and `ttyd`; the Claude pre-tool hook routes risky shell actions back into the gateway, preserving governance even for interactive sessions.

- `src/runtime/claude-code-adapter.ts`
- `src/edge/launcher.ts`
- `terminal/claude-launch.sh`
- `terminal/gate-hook.sh`
- `src/edge/session-backend.ts`

Material infrastructure is Node.js, built-in SQLite (`node:sqlite`), tmux, ttyd, and optionally systemd/nginx/Tailscale. Secrets are tenant/principal scoped via `src/edge/secrets.ts`; production vault replacement is an intended seam.

#### Edge, API, Console, and Integrations
The server exposes browser console/API routes, authentication/team management, approvals, live audit/session views, and terminal access. Edge modules adapt inbound channels, schedules, automation, connectors, LLM/media services, and operational maintenance into the kernel rather than embedding these concerns in governance.

- `src/server.ts`
- `src/edge/router.ts`
- `src/edge/triggers.ts`
- `src/connectors/connectors.ts`
- `web/src/App.tsx`

Supported integration boundaries include Slack, Discord, Telegram, GitHub, ClickUp, and Composio (`src/connectors/`). The React/Vite app in `web/` is a separate frontend; `public/console.html` also supports the Node-served console path.

Main entry points: [`src/gateway/gateway.ts`](https://github.com/vikasprogrammer/agent-os/blob/main/src/gateway/gateway.ts) (Governed effect gateway), [`src/kernel.ts`](https://github.com/vikasprogrammer/agent-os/blob/main/src/kernel.ts) (Tenant kernel), [`src/server.ts`](https://github.com/vikasprogrammer/agent-os/blob/main/src/server.ts) (Server and API), [`src/core/run.ts`](https://github.com/vikasprogrammer/agent-os/blob/main/src/core/run.ts) (Run lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Console"]
  node_startup["CLI / server startup<br/>Node entrypoint<br/>[index.ts]"]
  node_server["Server and API<br/>HTTP server<br/>[server.ts]"]
  node_console["React console<br/>frontend<br/>[App.tsx]"]
  node_router["Edge router<br/>channel adapter<br/>[router.ts]"]
end

subgraph group_control["Tenant Control Plane"]
  node_kernel{{"Tenant kernel<br/>runtime composition<br/>[kernel.ts]"}}
  node_tenant_registry["Tenant registry<br/>tenant router<br/>[tenant-registry.ts]"]
  node_data_home[("Workspace data home<br/>storage boundary<br/>[home.ts]")]
  node_orchestrator["Run orchestrator<br/>agent scheduler<br/>[orchestrator.ts]"]
  node_run["Run lifecycle<br/>execution state<br/>[run.ts]"]
  node_state[("SQLite control state<br/>state store<br/>[db.ts]")]
  node_memory[("Knowledge memory<br/>memory store<br/>[index.ts]")]
end

subgraph group_governance["Governance Gateway"]
  node_gateway{{"Governed effect gateway<br/>capability chokepoint<br/>[gateway.ts]"}}
  node_capabilities["Capability registry<br/>plugin boundary<br/>[registry.ts]"]
  node_policy["Policy and risk rules<br/>policy engine<br/>[policy.ts]"]
  node_approvals["Approval queue<br/>human control<br/>[approvals.ts]"]
  node_budget["Budget controls<br/>cost guard<br/>[budget.ts]"]
  node_audit["Append-only audit<br/>audit log<br/>[audit.ts]"]
end

subgraph group_execution["Runtime &amp; Integrations"]
  node_runtime["Claude Code runtime<br/>runtime adapter"]
  node_session_backend["Terminal session backend<br/>interactive session<br/>[session-backend.ts]"]
  node_connectors["External connectors<br/>integration adapters<br/>[connectors.ts]"]
  node_secrets["Tenant scoped secrets<br/>secret provider<br/>[secrets.ts]"]
end

node_startup -->|"starts"| node_server
node_server -->|"serves"| node_console
node_server -->|"routes requests"| node_router
node_router -->|"selects tenant"| node_tenant_registry
node_tenant_registry -->|"creates runtime"| node_kernel
node_kernel -->|"scopes storage"| node_data_home
node_kernel -->|"assembles"| node_orchestrator
node_kernel -->|"uses"| node_state
node_kernel -->|"uses"| node_memory
node_orchestrator -->|"creates and drives"| node_run
node_run -->|"executes through"| node_runtime
node_runtime -->|"requests effects"| node_gateway
node_session_backend -->|"pre-tool hook"| node_gateway
node_server -->|"terminal access"| node_session_backend
node_gateway -->|"classifies risk"| node_policy
node_gateway -->|"queues yellow/red"| node_approvals
node_approvals -->|"resumes decision"| node_run
node_gateway -->|"reserves/debits"| node_budget
node_gateway -->|"resolves invocation"| node_capabilities
node_gateway -->|"appends event"| node_audit
node_audit -->|"mirrors for views"| node_state
node_capabilities -->|"invokes effects"| node_connectors
node_connectors -->|"uses credentials"| node_secrets

click node_startup "https://github.com/vikasprogrammer/agent-os/blob/main/src/index.ts"
click node_server "https://github.com/vikasprogrammer/agent-os/blob/main/src/server.ts"
click node_console "https://github.com/vikasprogrammer/agent-os/blob/main/web/src/App.tsx"
click node_router "https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/router.ts"
click node_kernel "https://github.com/vikasprogrammer/agent-os/blob/main/src/kernel.ts"
click node_tenant_registry "https://github.com/vikasprogrammer/agent-os/blob/main/src/tenant-registry.ts"
click node_data_home "https://github.com/vikasprogrammer/agent-os/blob/main/src/home.ts"
click node_orchestrator "https://github.com/vikasprogrammer/agent-os/blob/main/src/core/orchestrator.ts"
click node_run "https://github.com/vikasprogrammer/agent-os/blob/main/src/core/run.ts"
click node_state "https://github.com/vikasprogrammer/agent-os/blob/main/src/state/db.ts"
click node_memory "https://github.com/vikasprogrammer/agent-os/blob/main/src/memory/index.ts"
click node_gateway "https://github.com/vikasprogrammer/agent-os/blob/main/src/gateway/gateway.ts"
click node_capabilities "https://github.com/vikasprogrammer/agent-os/blob/main/src/capabilities/registry.ts"
click node_policy "https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/policy.ts"
click node_approvals "https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/approvals.ts"
click node_budget "https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/budget.ts"
click node_audit "https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/audit.ts"
click node_runtime "https://github.com/vikasprogrammer/agent-os/blob/main/src/runtime/claude-code-adapter.ts"
click node_session_backend "https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/session-backend.ts"
click node_connectors "https://github.com/vikasprogrammer/agent-os/blob/main/src/connectors/connectors.ts"
click node_secrets "https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/secrets.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_startup,node_server,node_console,node_router toneBlue
class node_kernel,node_tenant_registry,node_data_home,node_orchestrator,node_run,node_state,node_memory toneAmber
class node_gateway,node_capabilities,node_policy,node_approvals,node_budget,node_audit toneMint
class node_runtime,node_session_backend,node_connectors,node_secrets toneRose
```

## Components

### Entry & Console

- [CLI / server startup](https://github.com/vikasprogrammer/agent-os/blob/main/src/index.ts): Node entrypoint · Starts API, console, and terminal proxy. · `src/index.ts`
- [Server and API](https://github.com/vikasprogrammer/agent-os/blob/main/src/server.ts): HTTP server · Exposes console, API, approvals, audit, and terminal routes. · `src/server.ts`
- [React console](https://github.com/vikasprogrammer/agent-os/blob/main/web/src/App.tsx): frontend · `web/src/App.tsx`
- [Edge router](https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/router.ts): channel adapter · Adapts inbound routes and channels into the kernel. · `src/edge/router.ts`

### Tenant Control Plane

- [Tenant kernel](https://github.com/vikasprogrammer/agent-os/blob/main/src/kernel.ts): runtime composition · Assembles the tenant-scoped agent runtime. · `src/kernel.ts`
- [Tenant registry](https://github.com/vikasprogrammer/agent-os/blob/main/src/tenant-registry.ts): tenant router · Optionally creates isolated runtimes per tenant. · `src/tenant-registry.ts`
- [Workspace data home](https://github.com/vikasprogrammer/agent-os/blob/main/src/home.ts): storage boundary · Separates software from private tenant workspace data. · `src/home.ts`
- [Run orchestrator](https://github.com/vikasprogrammer/agent-os/blob/main/src/core/orchestrator.ts): agent scheduler · Creates and drives agent-task runs. · `src/core/orchestrator.ts`
- [Run lifecycle](https://github.com/vikasprogrammer/agent-os/blob/main/src/core/run.ts): execution state · Tracks execution, approval waits, completion, and failure. · `src/core/run.ts`
- [SQLite control state](https://github.com/vikasprogrammer/agent-os/blob/main/src/state/db.ts): state store · Stores tenant control-plane records and mirrored audit views. · `src/state/db.ts`
- [Knowledge memory](https://github.com/vikasprogrammer/agent-os/blob/main/src/memory/index.ts): memory store · `src/memory/index.ts`

### Governance Gateway

- [Governed effect gateway](https://github.com/vikasprogrammer/agent-os/blob/main/src/gateway/gateway.ts): capability chokepoint · All registered external effects traverse this pipeline. · `src/gateway/gateway.ts`
- [Capability registry](https://github.com/vikasprogrammer/agent-os/blob/main/src/capabilities/registry.ts): plugin boundary · Normalizes and resolves allowed external actions. · `src/capabilities/registry.ts`
- [Policy and risk rules](https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/policy.ts): policy engine · Classifies effects as green, yellow, red, or denied. · `src/governance/policy.ts`
- [Approval queue](https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/approvals.ts): human control · Authorized decisions resume or reject suspended runs. · `src/governance/approvals.ts`
- [Budget controls](https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/budget.ts): cost guard · Reserves and debits effect cost and token caps. · `src/governance/budget.ts`
- [Append-only audit](https://github.com/vikasprogrammer/agent-os/blob/main/src/governance/audit.ts): audit log · Durable per-run record of governed effects. · `src/governance/audit.ts`

### Runtime & Integrations

- [Claude Code runtime](https://github.com/vikasprogrammer/agent-os/blob/main/src/runtime/claude-code-adapter.ts): runtime adapter · Launches governed agent sessions in agent folders. · `src/runtime/claude-code-adapter.ts`
- [Terminal session backend](https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/session-backend.ts): interactive session · Backs tmux and ttyd terminal access. · `src/edge/session-backend.ts`
- [External connectors](https://github.com/vikasprogrammer/agent-os/blob/main/src/connectors/connectors.ts): integration adapters · Slack, GitHub, Discord, Telegram, ClickUp, and Composio boundary. · `src/connectors/connectors.ts`
- [Tenant scoped secrets](https://github.com/vikasprogrammer/agent-os/blob/main/src/edge/secrets.ts): secret provider · Resolves secrets by tenant and principal. · `src/edge/secrets.ts`

## Connections

- CLI / server startup → Server and API: starts
- Server and API → React console: serves
- Server and API → Edge router: routes requests
- Edge router → Tenant registry: selects tenant
- Tenant registry → Tenant kernel: creates runtime
- Tenant kernel → Workspace data home: scopes storage
- Tenant kernel → Run orchestrator: assembles
- Tenant kernel → SQLite control state: uses
- Tenant kernel → Knowledge memory: uses
- Run orchestrator → Run lifecycle: creates and drives
- Run lifecycle → Claude Code runtime: executes through
- Claude Code runtime → Governed effect gateway: requests effects
- Terminal session backend → Governed effect gateway: pre-tool hook · Risky shell actions are routed back for governance.
- Server and API → Terminal session backend: terminal access
- Governed effect gateway → Policy and risk rules: classifies risk
- Governed effect gateway → Approval queue: queues yellow/red
- Approval queue → Run lifecycle: resumes decision
- Governed effect gateway → Budget controls: reserves/debits
- Governed effect gateway → Capability registry: resolves invocation
- Governed effect gateway → Append-only audit: appends event
- Append-only audit → SQLite control state: mirrors for views
- Capability registry → External connectors: invokes effects
- External connectors → Tenant scoped secrets: uses credentials