AKOS — API Knowledge Operating System
Persistent, 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.
Live: https://akos.spboucher.ai (UI) · /api/v1 (REST) · /mcp (MCP, Bearer token) · /docs (OpenAPI, login required).
Quick start (operator / researcher)
# CLI
uv tool install --from /path/to/akos akos # or: pip install -e .
akos login --url https://akos.spboucher.ai # mints a scoped token into ~/.config/akos/config.json
akos status && akos doctor
akos search "exchange rates"
akos inspect frankfurter.frankfurter-exchange-rates
akos discover --openapi-url https://…/openapi.json --name "My API" --license CC-BY-4.0
akos execute -p worldbank.world-bank-indicators --op get-v2-country-ca-indicator-ny-gdp-mktp-cd -q format=json -q date=2015:2023
akos research export --dataset <id> --output ./export/ # manifest.json, acquire.py, transform.py, lineage.json, METHODS.md …
# Claude Code (adds only the `akos` MCP server; nothing else in your settings is touched)
AKOS_TOKEN=akos_… integrations/claude-code/install.sh --with-hooksLayout
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.
Development
uv sync --frozen && cp .env.example .env # fill secrets; Postgres 17 with pg_trgm + pgcrypto
python -m akos bootstrap && python -m akos web # + `python -m akos worker`, `python -m akos proxy`
cd web && pnpm install --frozen-lockfile && pnpm build
make test # offline suite (mock API, akos_test DB)
make test-node # macOS: sandbox-exec enforcement + backup/restore drill