---

name: runtime-service description: "Run and debug the MineContext/OpenContext Python backend runtime, APIs, configuration, storage, capture, processing, generation, chat, and local smoke checks." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Runtime service

Use this sub-skill for MineContext/OpenContext backend runtime tasks: starting opencontext, configuring model/storage/auth/prompt settings, uploading or capturing context, calling FastAPI endpoints, debugging content generation, chat/completion flows, monitoring, and deterministic local smoke checks.

Route Electron app builds, PyInstaller packaging, signing, helper binaries, and frontend release tasks to desktop-packaging. For cross-component orientation read the root architecture; for install/import or runtime-vs-packaging failures read the root troubleshooting guide before the workflow-specific troubleshooting page here.

Runtime entry checklist

1. Confirm the installed backend package imports and the CLI is present:

   python -c "import opencontext; print(opencontext.__version__)"
   opencontext --help
   

2. Start from a known CONTEXT_PATH if you need disposable local data:

   mkdir -p .minecontext-data
   CONTEXT_PATH="$PWD/.minecontext-data" opencontext start --config config/config.yaml --host 127.0.0.1 --port 1733
   

3. Check health before calling data routes:

   curl -s http://127.0.0.1:1733/health
   curl -s http://127.0.0.1:1733/api/health
   

4. If API authentication is enabled, send X-API-Key: <key> or ?api_key=<key> on protected routes; never print or persist the key in notes.

5. Do not run screenshot, web-link, model-validation, generation, chat, or completion workflows until the user confirms screen/browser/network/model access and supplies non-secret credentials through config, environment, or the settings API.

Reference map

• references/api-reference.md: read when calling HTTP routes, matching request bodies, interpreting response envelopes, or debugging route-family ownership.
• references/configuration.md: read before editing YAML, CONTEXT_PATH, model settings, storage backends, prompt language/files, content-generation intervals, or API auth.
• references/data-formats.md: read when creating raw context payloads, interpreting processed contexts, selecting supported document formats, or mapping storage tables and context types.
• references/workflows.md: read for concrete CLI/API workflows covering startup, uploads, screenshots, folder monitoring, web links, context search, generation, chat/completions, monitoring, and local smokes.
• references/troubleshooting.md: read when a runtime workflow fails after the first health/config checks.
• scripts/smoke_folder_monitor.py: run for a deterministic CPU-only folder-monitor create/update/delete check with mocked storage cleanup.
• scripts/smoke_document_text.py: run for a CPU-only text-document processing smoke that builds an isolated temporary runtime config and does not require model credentials.

What this sub-skill owns

• opencontext start, opencontext --help, OpenContext.initialize(), capture startup, FastAPI app state, and health checks.
• FastAPI route families for web pages, settings, context search, screenshots, document/web-link uploads, vault documents, generated content, monitoring, events, completions, context-agent chat, conversations, and messages.
• Runtime configuration: config.yaml, environment interpolation, CONTEXT_PATH, model settings, prompt YAML, user settings, API auth, storage, content-generation tasks, capture, and processing.
• Capture/processing/storage workflows for folders, documents, screenshots, web links, ChromaDB, Qdrant, SQLite, and supported data formats.
• User-facing generation and consumption flows: activities, tips, todos, reports, context-agent chat, streaming, message interruption, and intelligent completion.

Boundaries and safety

• Do not document or depend on the original repository checkout for normal use; prefer installed opencontext plus bundled references/scripts.
• Do not include API keys, private model endpoints, local virtualenv paths, package install prefixes, or user data paths in generated notes.
• Treat API settings updates, database resets, prompt imports, browser capture, screenshot capture, and generation calls as user-data or credential-sensitive.
• Use desktop-packaging for executable/app packaging tasks; this sub-skill only covers the backend after it is installed or running.