| name | cartographer-ops |
| description | Configure, operate, troubleshoot, or upgrade a Cartographer server or client; connect agents and manage Knowledge Bases. |
| version | 1.0 |
Cartographer Operations
Mental model
Cartographer is one server process over a data directory whose direct subfolders are Knowledge
Bases (KBs). Connect clients to it with cartographer connect; agents use the MCP server rather
than editing KB files. Every KB write is committed to git, and a configured remote is synchronized
around writes.
CLI surface
| Command | Use it when |
|---|
cartographer serve | Starting the server directly, for development or a custom deployment. |
cartographer service install|status|restart | Installing, checking, or restarting the native local service. |
cartographer kb create <name> | Creating the first local KB in the service data directory. |
cartographer kb clone <remote> [name] | Mounting an existing OKF KB remote in the service data directory. |
cartographer connect [provider|all] [--agents a,b] | Connecting one or more detected agent clients to a server. |
cartographer status | Checking client configuration and provisioning drift. |
cartographer sync | Realigning provisioned skills, agents, hooks, and instructions. |
cartographer disconnect [provider|all] [--agents a,b] | Removing Cartographer-managed client configuration. |
cartographer version | Checking the installed binary version. |
--agents claude,codex selects a comma-separated subset for connect or disconnect; do not
combine it with the positional provider. connect probes the server before writing: a reachable
server with no KBs needs kb create followed by service restart.
Configuration
Server settings resolve as flag > environment > YAML > default. Keep secrets in environment
variables or the platform secret store, not in a committed YAML file.
| Variable | Purpose |
|---|
CARTOGRAPHER_KB | One or more explicit KB paths. |
CARTOGRAPHER_DATA | Data directory whose direct subfolders are discovered as KBs. |
CARTOGRAPHER_HTTP | HTTP listen address, such as :8080. |
CARTOGRAPHER_AUTH | Explicit auth mode: on, off, or automatic when unset. |
CARTOGRAPHER_TOKENS | Bearer tokens, including optional per-KB scopes. |
CARTOGRAPHER_GIT_SYNC | Set false only when remote git synchronization around writes is intentionally disabled. |
CARTOGRAPHER_OLLAMA | Ollama base URL that enables semantic search. |
Diagnosis playbook
- Check
GET /health. Its status, version, ready, and kbs fields distinguish a live
process from a usable server.
- If
ready is false or no KBs are mounted, run cartographer kb create <name> and then
cartographer service restart for a local service.
- If client artifacts are stale or missing, run
cartographer sync, then restart the affected
agent session so it reloads MCP configuration and skills.
- If concepts are degraded after a git conflict, use the
kb-conflict-resolve skill; do not
repair their files outside Cartographer.
- If the binary and running service differ, run
cartographer service restart after upgrading.
Upgrade
- macOS:
brew upgrade --cask beppetemp/tap/cartographer, then cartographer service restart.
- Kubernetes: update the Cartographer image tag in the deployment manifest and wait for rollout.
Never do
- Do not edit KB concept files directly: use Cartographer MCP tools so validation, git commits,
and synchronization invariants apply.
- Do not hand-edit provisioned MCP entries or
.cartographer.yaml; use connect, sync, and
disconnect so Cartographer can track and safely prune its own files.
Further reading
