Oaken Core · An async pipeline and a plugin loader

Pre-alphaLocal-firstOpen source

★ Star this repo on GitHub View on GitHub Report an issue Apache-2.0 license

Oaken Core takes items in, formats them, triages them, stores them and runs the work around them. It has no nouns of its own: a message, a person or a CVE is a plugin's idea. Products are thin coats of plugins over it.

What it is for

One pipeline, many products. Providers bring items in, formatters split them into parts, triagers rate them, an ingestor stores them. Each is a plugin behind a small, declared contract.
Nothing happens by accident. Every step is a durable job, and a change made through any door (CLI, API, MCP, console) is a proposal until a person confirms it.
Outside text is data. Text from outside is never an instruction to the system or to a model.
Plugins describe themselves. A plugin declares its settings, its row, and whether it is a template; the console draws the same row everywhere.

The documents

Start

Set up Oaken Core from scratch

A first-time setup of Oaken Core: install, set OAKEN_HOME, oaken start, oaken plugins, oaken plugin add KIND.NAME, and the console on 127.0.0.1:62536.

Start

Store credentials in your keyring

How Oaken Core uses the OS keyring: the service and entry names, oaken secret set, status and delete, what config.toml refuses, and what the no-keyring error means.

Start

Settings, storage and the event log

oaken settings get and set, config validate and save, reload, storage and vacuum, the answer cache, the event log, the log and the change log.

Concepts

Architecture overview

Intake, labels, queues, jobs, the router, the four doors, the plugin kinds and the databases.

Concepts

Events, jobs and the scheduler

The event bus and logs, the durable job queues with leases and retries, queue pause, and the scheduler.

Concepts

Software map

The layered map of Oaken Core's components and their build status.

Concepts

The swarm

External agents that lease jobs: opt-in config, scoped tokens, quotas, validated results, and the HTTP and MCP doors they work through.

Concepts

The daemon and the local API

The core daemon: startup and shutdown order, the runtime file, the API token, the Host, Origin and content-type guards, event streaming, the console listener, and the threat model.

Concepts

Writing a plugin

How to write a plugin for core: kinds, BasePlugin and @command, template plugins, config_model, tags, migrations, labels, versions, the UI contract, contract tests and entry points.

Concepts

The model router

The router ladder (cache, near-duplicate shortcut, capped small model, one escalation), backends and routes, the cache key, the ledger, the daily token budget and Deferred.

Concepts

Prompt safety

UntrustedText and its delimiters, the triage llm plugin as the worked example, structured answers, and the confidential rule: local always, lan on an allowlist, hosted never.

Concepts

Operations

The operation registry, permission classes, the confirm gate and proposals, MCP exposure you control, plugin operations, the OpenAPI document and the CLI exit codes.

Project

Architecture decisions

Every architecture decision record, with its status and date.