Runtime

OpenCanon runs as a local service plus isolated project runtimes. The CLI, MCP, hooks, and browser diagnostics all read the same local API.

Service

The global service discovers OpenCanon projects, owns the cross-project registry, and lazily starts project runtimes when a command needs repository data.

01opencanon status
02opencanon service start
03opencanon service status --format json
04opencanon service open

Project runtime

A project runtime owns one repository. It indexes source files, generates authoring types, stores derived SQLite state, tracks Activity, serves Search, and runs Proof against scoped files or the whole project.

01opencanon project check
02opencanon project status --format json
03opencanon project index
04opencanon project logs --tail 200
05opencanon project open
06opencanon project stop
07opencanon project start --foreground

State

Committed Project Canon lives under opencanon/ and generated docs live under docs/opencanon/. Derived state lives under .opencanon/ and stays ignored by Git. The OpenCanon home directory stores service registry and installed runtime metadata.

Engine

The native engine handles watching, hashing, fact extraction, code graph indexing, and affected-file calculation. JavaScript and TypeScript facts, Python facts, dependency metadata, semantic chunks, and generated project constants are all runtime-derived.

Updates

Runtime updates are manifest-driven. The CLI selects the current target, checks schema and Node compatibility, verifies asset hashes, and refuses to write while the service or current project runtime is running. Runtime updates do not mutate project files directly; Doctor owns managed project artifact repair through opencanon doctor --fix.

01opencanon service stop
02opencanon project stop
03opencanon update check --manifest ./opencanon-runtime-manifest.json
04opencanon update apply --manifest ./opencanon-runtime-manifest.json
05opencanon doctor --fix

API

The service exposes project discovery and project-runtime proxy endpoints. Project runtimes expose Project Canon, Proof, Knowledge, Activity, Health, file, graph, and context endpoints for local clients.