![\"Molenkopf](\"packages/dashboard/public/molenkopf-logo.png\"){kind=logo}
\n\n \n
\n Local control plane for coding-agent traffic.\n
\n\nMolenkopf is an unofficial local/self-hosted gateway. It is not affiliated with,\nendorsed by, or sponsored by Anthropic or OpenAI.\n\nMolenkopf sits between coding agents and provider or runtime backends. It proxies\nOpenAI-compatible and Anthropic/Claude API traffic, can bridge local Claude CLI\nand Codex CLI runtimes, and gives teams local keys, routing, usage, budgets,\nredaction, audit manifests, and dashboard controls.\n\nThe core safety pipeline is fixed: secret redaction, content classification,\naudit manifests, and redacted SSE events are always owned by Molenkopf. Optional\nplugins extend the pipeline; they do not replace core safety behavior.\n\nProduct intent and non-negotiable plugin semantics live in\n`docs/PRODUCT_INTENT.md` and `docs/MOLENKOPF_PLUGIN_API.md`.\n\n## Quickstart\n\n### npm package\n\nRequires Node.js 24 or newer.\n\n```bash\nnpm install -g @bothat-io/molenkopf\nnode -e \"require('node:fs').writeFileSync('.env','MOLENKOPF_SESSION_SECRET='+require('node:crypto').randomBytes(32).toString('hex')+'\\n')\"\nmolenkopf proxy\n```\n\n### Docker\n\n```bash\nnode -e \"require('node:fs').writeFileSync('.env','MOLENKOPF_SESSION_SECRET='+require('node:crypto').randomBytes(32).toString('hex')+'\\n')\"\ndocker run --rm --env-file .env -p 127.0.0.1:8787:8787 -v molenkopf-data:/data ghcr.io/bothat-io/molenkopf:latest\n```\n\n### Source checkout\n\n```bash\nnpm run bootstrap\nexport MOLENKOPF_SESSION_SECRET=\"$(node -e \"process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))\")\"\nnpm run dev\n```\n\nOpen `http://127.0.0.1:8787/` after startup.\nFor source hygiene checks, keep private env files outside the repository or\nexport variables in your shell. A root `.env` is local runtime state and makes\n`check:sensitive-workspace` fail by design.\n\nUse `docs/DEPLOYMENT.md` when you need a different port or non-loopback access.\n\n## Screenshot\n\n\n\n## Safety Notice\n\nDo not run Molenkopf blindly with real provider accounts, private repositories,\nor browser sessions. Review `SECURITY.md` first,\nkeep source runs on the default loopback bind, and treat `.molenkopf/`, audit\nfiles, retrieval stores, databases, env files, and local credential stores as\nsensitive local state.\n\n## Implemented Baseline\n\nBuilt now:\n\n- Local HTTP proxy bound to `127.0.0.1` by default.\n- Transparent streaming gateway for OpenAI- and Anthropic-compatible traffic via\n base-URL interception (`OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`). Responses\n are streamed through byte-for-byte where possible (SSE, gzip, headers\n preserved); the agent runs normally and its context stream flows through\n Molenkopf.\n- Transparent by default: the request body is never altered unless\n `context-reducer-plugin` is explicitly enabled. Provider-input reduction is\n opt-in and only the reducer may mutate request bodies.\n- Per-agent multi-account routing: each agent (`x-molenkopf-agent`) routes to its bound provider/account; config `profiles`/`agents` resolve to providers.\n- Real token accounting: upstream `usage` is read from the provider response and recorded as\n real input/output tokens (not only a chars/4 estimate).\n- `project-memory-plugin`: builds a deterministic local project memory index and\n optional Obsidian export without mutating provider requests.\n- Static pipeline with request IDs, redaction, classification, optional reducer\n mutation, audit, SSE events, and upstream routing.\n- Local API under `/__molenkopf/*`: bootstrap endpoints for health, session\n status, and first-run admin creation, user-scoped usage/key endpoints, and admin-only\n provider/plugin/agent/stats/events/config metadata plus retention purge.\n- Dashboard shell served at `/__molenkopf/dashboard` with Overview and Admin\n views backed by an isolated React/Vite dashboard package. Dedicated Providers,\n Plugins, Requests, Audit, Agents, and Settings views are planned.\n- Plugin pages are local HTML surfaces under `/__molenkopf/plugins/:id/page`;\n context reducer, token optimizer, and project memory pages read scoped plugin\n data endpoints and show explicit load errors instead of fake empty workspaces.\n- The context reducer plugin owns provider-input token reduction. Token optimizer\n is observer-only and reports reducer evidence; project memory indexes local\n project structure without request mutation.\n- Practical dashboard and proxy connection guide: `docs/MOLENKOPF_USAGE.md`.\n- JSON config startup target for providers, agents, and plugin policies:\n `docs/MOLENKOPF_JSON_CONFIG_PLAN.md`.\n- Multi-provider env setup: `docs/MOLENKOPF_PROVIDER_ENV.md`.\n- Root `/` redirects to the local dashboard; upstream API traffic stays on `/v1/...`.\n- Claude/Anthropic-compatible target resolution through `ANTHROPIC_BASE_URL`; Molenkopf-owned CLI runtime bridging exists for local `claude` and `codex` child processes.\n- Profile routing primitives for fixed, manual, and failover routing with env credentials, budgets, and health summaries.\n- Local plugin SDK with explicit permissions and remote plugin loading disabled.\n- CI mode primitives for PR context packing and audit artifacts.\n\nExplicitly not connected:\n\n- Remote issue-tracker integration.\n- Remote plugin installation.\n- Login with provider consumer accounts, provider account-session brokering,\n subscription quota pooling, or subscription quota redistribution.\n- Credential-file scanning, config-file credential storage, Claude/Codex auth\n file import, or copied provider session storage.\n\n## Security Model\n\nCore and proxy use Node.js built-ins only. Molenkopf API keys are stored as hashes, and Local API responses hide provider credentials. Molenkopf stores BYO API keys/env refs/gateway credentials, not provider account sessions. Local Claude CLI and Codex CLI runtimes authenticate locally through their installed clients. Proxy traffic on `/v1/...` requires a valid Molenkopf API key. The default upstream route can forward incoming auth headers only when the selected profile requires it; configured provider profiles strip incoming client auth and inject the server-side credential at the forwarding boundary. Prompts and responses are not logged in full. Source code and diffs pass through in safe mode.\n\nBefore the first admin exists, only health, session status, and browser first-run\nadmin creation are usable. After setup, Local API metadata is role-gated: normal\nusers get scoped usage and key data, while provider, plugin, agent, routing,\nstats, events, and retention endpoints are admin-only.\n\nUse `--allow-public-bind` only when you intentionally want to bind outside\nlocalhost. If Docker is published publicly before an admin exists, the first-run\nscreen is reachable there until the first admin is created.\n\n## Control Plane Usage\n\nRoot `/` opens the dashboard at `/__molenkopf/dashboard`; upstream agent traffic\nstays on `/v1/...` and requires a Molenkopf API key.\n\n`x-molenkopf-agent` is optional local request metadata. It may select an\nexplicit agent binding only when that binding is already allowed for the\nauthenticated key, team, and provider policy; otherwise the request fails\nclosed.\n\nManual provider switching happens in the Admin provider section or by posting `{ \"id\": \"openai-env\" }` to `/__molenkopf/providers/select`. Explicit provider profiles, API-key scopes, team allowlists, and routing mode are enforced before forwarding; manual selection remains the default route when no explicit profile is attached.\n\nMultiple provider profiles can be declared with `molenkopf.config.json` or\n`MOLENKOPF_PROVIDER_IDS`. JSON profiles must reference credentials with\n`auth.credentialRef` such as `env:OPENAI_API_KEY`; inline credentials are\nrejected in file config. Local API responses hide credential values and show\nonly `credentialRef` plus configured state. Selected configured profiles inject\ntheir credential at the forwarding boundary.\n\nUsers, teams, projects, and Molenkopf API keys are managed in the Dashboard.\nOverview is the signed-in user's status, usage, teams, members, and project-key\nsurface. Admin contains provider, plugin, user, team, and system controls.\nProjects are required key/workload labels; teams carry provider policy and usage\nscope. See `docs/MOLENKOPF_USAGE.md` for the workflow and Local API endpoints.\n\nPlugin toggles happen in the Admin plugin section or by posting `{ \"id\": \"context-reducer-plugin\", \"enabled\": true }` to `/__molenkopf/plugins/toggle`. Plugins are optional extensions; core safety, storage, audit, event, and routing code is not exposed as plugins and cannot be disabled through plugin controls. Remote plugin loading is disabled.\n\nAgent drafts are stored as local proxy metadata through `/__molenkopf/agents/draft`; raw token fields are rejected and only `tokenHash` is accepted. The dashboard keeps a `localStorage` fallback if the local API is unavailable. These drafts are routing metadata, not provider credentials.\n\nPlugin pages open in standalone windows from `/__molenkopf/plugins/context-reducer-plugin/page`, `/__molenkopf/plugins/token-optimizer-plugin/page`, and `/__molenkopf/plugins/project-memory-plugin/page`. Plugin pages group by project/key where available and surface plugin-data failures explicitly.\n\n## Limitations\n\nProvider token accounting uses upstream `usage` when present and falls back to bounded estimates for local reducer pressure. JSON summaries are readable summaries, not guaranteed valid JSON. v0.1 does not retry provider failures automatically and request-side reduction remains opt-in.\n\nBe careful with secrets and private repositories. Molenkopf reduces accidental\nexposure, but local retrieval stores still contain bounded redacted excerpts.\nThey do not support full-original recovery and should be treated as sensitive\nlocal artifacts.\n\n## License\n\nMIT License. Copyright (c) 2026 bothat.io and Molenkopf contributors.\n","readmeFilename":"README.md"}