1# AKOS — API Knowledge Operating System23Persistent, enforceable, executable API knowledge for Claude Code and other agents: a PostgreSQL registry of versioned API Knowledge Packages (AKPs), a governed execution gateway with provenance, a compiler that turns documentation into tested Python/TypeScript clients and MCP tool contracts, a provenance engine with reproducible research exports, a credential vault (keychain references only), knowledge-debt and drift tracking, an MCP endpoint, a CLI and a responsive web console.45**Live:** https://akos.spboucher.ai (UI) · `/api/v1` (REST) · `/mcp` (MCP, Bearer token) · `/docs` (OpenAPI, login required).67## Quick start (operator / researcher)8```bash9# CLI10uv tool install --from /path/to/akos akos # or: pip install -e .11akos login --url https://akos.spboucher.ai # mints a scoped token into ~/.config/akos/config.json12akos status && akos doctor13akos search "exchange rates"14akos inspect frankfurter.frankfurter-exchange-rates15akos discover --openapi-url https://…/openapi.json --name "My API" --license CC-BY-4.016akos execute -p worldbank.world-bank-indicators --op get-v2-country-ca-indicator-ny-gdp-mktp-cd -q format=json -q date=2015:202317akos research export --dataset <id> --output ./export/ # manifest.json, acquire.py, transform.py, lineage.json, METHODS.md …1819# Claude Code (adds only the `akos` MCP server; nothing else in your settings is touched)20AKOS_TOKEN=akos_… integrations/claude-code/install.sh --with-hooks21```2223## Layout24`akos/` service code (api, gateway, registry, compiler, provenance, composition, vault, jobs, mcp_server, cli, sdk) · `web/` React UI · `tests/` unit/integration/security/e2e · `examples/` cross-source recipe + opaque MCP demos · `scripts/` backup/restore/bench · `integrations/claude-code/` installer + hook · `infra/akos.mld.json` deployment manifest · `docs/` architecture, threat model, operations, security review, acceptance.2526## Development27```bash28uv sync --frozen && cp .env.example .env # fill secrets; Postgres 17 with pg_trgm + pgcrypto29python -m akos bootstrap && python -m akos web # + `python -m akos worker`, `python -m akos proxy`30cd web && pnpm install --frozen-lockfile && pnpm build31make test # offline suite (mock API, akos_test DB)32make test-node # macOS: sandbox-exec enforcement + backup/restore drill33```34