Architecture

Ódinn Forge is a small Node.js workspace organized around one shared execution boundary.

console / CLI / plans
          |
          v
 authenticated gateway or local CLI
          |
          v
 policy-gated kernel ----- model/provider adapters
          |
          +-- web and isolated browser tools
          +-- projects, sessions, goals, and memory
          +-- jobs, approvals, and recovery journals
          +-- SQLite run ledger and artifacts
          +-- seven gated Labs
          +-- signed audit events

Interfaces

The CLI and local console are two views over the same runtime concepts. The gateway supplies authenticated HTTP and streaming interfaces for the console. The CLI is useful for onboarding, inspection, deterministic tools, state operations, and advanced workflows.

Kernel and policy

The kernel registers tools, normalizes model providers, manages memory and durable records, and routes execution through policy. Tool visibility never grants authority by itself.

Unknown tools receive a restrictive safety descriptor. Built-in tools and extension or MCP adapters cross the same audited boundary.

Providers

Provider adapters support API-key, OAuth, device, CLI, and OpenAI-compatible transports. The runtime normalizes request, retry, usage, and error behavior where possible, while live service behavior remains provider-dependent.

Durable state

Append-only record stores hold memory and user-facing entities. A signed audit journal records decisions and activity. SQLite stores runs, steps, content-addressed evidence, and Labs state. Jobs, approvals, and browser recovery are restart-safe.

Process boundary

Gateway tasks can run in forked workers for crash containment, timeout supervision, and bounded execution. These workers are not an OS security sandbox.

Repository layout

• apps/cli/ — user-facing CLI and onboarding
• apps/gateway/ — local gateway, console, and remote host
• packages/kernel/ — tools, providers, memory, jobs, extensions, Labs
• packages/policy/ — capability and security policy
• packages/protocol/ — shared request and audit contracts
• packages/store-file/ — append-only local stores
• packages/store-sqlite/ — run ledger persistence
• tests/ — unit, integration, security, platform, and release coverage

Continue with the Event ledger or the repository README.