vikasprogrammer/agent-os

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.