Agent-driven installation¶

Use this runbook whenever the user asks you to install Cartographer — a repository link and a conversation is the normal starting point, and it is enough. Execute every command in order; report the expected result before continuing.

Establish one input first: the git remote for the user's first Knowledge Base (KB). A KB is a git repository and its remote is what makes it durable and syncable, so the remote is required, and on this path it is almost always the thing nobody supplied. Ask for it now — an empty repository they own (GitHub, Gitea, or any git host) — rather than discovering at step 3 that you need a URL you do not have. Only if the user explicitly accepts a throwaway, local-only KB do you proceed without one.

1. Install Cartographer¶

Detect the platform:

uname -s

Expected output: Darwin on macOS or Linux. The installer supports those two and no others; on any other platform, stop and report it. On macOS, first check for Homebrew:

command -v brew

Expected output: the path to brew. If it is present, install Cartographer:

brew install beppetemp/tap/cartographer

Expected output: Homebrew reports that cartographer was installed. If brew is absent, install the current release instead:

curl -fsSL https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.sh | sh

Expected output: the installer reports the destination of the cartographer binary.

Confirm the binary is available:

cartographer version

Expected output: a Cartographer version.

2. Install the local service¶

cartographer service install

Expected output: the native user service is installed and started. It listens on http://127.0.0.1:39273 and its data directory is ready for KBs.

3. Mount the first KB¶

When the remote already contains a KB, mount it through Cartographer:

cartographer kb clone <git-remote-url> --restart

Expected output: KB "<name>" mounted at <data-dir>/<name>, followed by service restart and health guidance. Do not clone the repository into the service data directory yourself.

When the remote is an empty repository, create the KB in it:

cartographer kb create <name> --remote <git-remote-url> --restart

Expected output: KB "<name>" created at <data-dir>/<name>, then origin: <git-remote-url>, followed by service healthy.

Ask for a remote before running either command. Only if the user explicitly accepts a throwaway, local-only KB — not backed up and never synchronized — fall back to cartographer kb create <name> --no-remote --restart, and state that limitation back to them.

4. Connect the executing agent¶

First identify the installed provider name:

cartographer agents

Expected output: a table listing claude, opencode, codex, kiro, hermes, and antigravity with installation state. Connect the executing provider with --agents; for example, for Codex:

cartographer connect --agents codex

Expected output: the generated MCP configuration paths and a reminder to restart the agent session. With two or more mounted KBs, Cartographer creates one MCP entry per KB the client is bound to.

Ask which KBs this client should receive. On a first connect against a server mounting two or more KBs, connect requires the choice — it will not deliver all of them by default (D190), because everything a KB carries (skills, subagents, hooks, instructions, MCP descriptors) is delivered with it:

cartographer connect --agents codex --kb <name>          # repeatable, or comma-separated
cartographer connect --agents codex --kb all             # every mounted KB, recorded explicitly

In an interactive terminal the same choice is offered as a list after the connect form. Prefer the narrowest selection that does the job, and verify the result with cartographer status: the bound KBs are printed per provider, with explicit next to them.

A KB bound this way is readable from every directory on the machine. If the user works in two separate perimeters with the same client, offer the alternative before the first sync, because it is free only now (D193):

cartographer connect --agents codex --kb <name> --workspace <repository path>

That confines those KBs to one repository instead — their skills, subagents and hooks are materialized into that repository's own configuration and nowhere else. cartographer workspace bind/unbind/list manages it afterwards.

5. Verify the installation¶

cartographer version
curl -fsS http://127.0.0.1:39273/health
cartographer status

Expected output: a version, then health JSON containing "ready":true, then in-sync status with exit code 0.

Confirm the instructions actually reach the model, not just the disk. cartographer status and cartographer doctor now check the provider's own precedence chain (D189), but the provider's own tooling is the ground truth — for Codex:

codex debug prompt-input

Expected output: a cartographer:kb:* section. If it is absent while status reports the instructions installed, report it: a provider precedence rule Cartographer does not model yet.

connect provisioned the bundled skills, including cartographer-ops. Use that skill for ongoing operations, diagnosis, upgrades, and synchronization after installation. From there the bundled kb-create and kb-import skills take over: kb-create/references/artifacts.md for authoring the KB's skills, subagents, hooks and MCP descriptors, and kb-create/references/secrets.md for the SOPS encryption flow.

6. Tell the user to restart their agent session¶

This is a step you cannot perform: the session that must restart is the one you are running in. State it to the user explicitly, as the last thing you say:

Restart your agent session now. The MCP tools and the provisioned skills are loaded at session start, so until you do, Cartographer is installed but invisible to me.

Omitting this is the single most common way a correct installation is reported as broken.

Failures¶

Observed symptom	Next action
`command -v brew` has no output	Run the `install.sh` command in step 1.
The user's agent shows no Cartographer MCP tools after a successful `connect`	The session was not restarted. Repeat step 6 — this is not a failed install.
`cartographer status` exits non-zero immediately after install	The service may still be starting: wait a few seconds and retry once before diagnosing.
The service reports that port 39273 is busy	Stop or reconfigure the process using the port, then rerun `cartographer service install`.
`kb clone` reports a git authentication failure	Configure ambient credentials (an SSH agent for SSH remotes or a git credential helper for HTTPS), then rerun the same `kb clone` command.
`kb clone` reports a host key that is not in `known_hosts`	Connect once with `ssh <host>` to review and accept the key yourself, then rerun. The clone never accepts a host key on your behalf (D173).
`kb clone` times out	The forge did not answer within the budget: check the remote is reachable, then rerun with `--timeout <duration>` if the repository is simply large.
`kb clone`/`kb create` refuse because the client points at a remote server	These commands act on the local server's data dir. Mount the KB on the remote deployment instead, or pass `--local` (act locally anyway) or `--data <dir>` (name the target).
`kb clone` says `not an OKF KB`	Use the `kb-import` skill to import the remote into an OKF KB, push it, then rerun `kb clone`.
`kb create` says a KB needs a git remote	Ask the user for an empty repository URL and rerun with `--remote <url>`; use `--no-remote` only if they explicitly accept a local-only KB.
`kb create --remote` fails to push (non-fast-forward, or the remote is not empty)	The repository already has content: mount it with `cartographer kb clone <git-remote-url> --restart` instead.
`kb create --remote` reports a git authentication failure	Configure ambient credentials (an SSH agent for SSH remotes or a git credential helper for HTTPS), then rerun the same command. The scaffold is deliberately kept (D156): the command prints how to fix the author/push, or how to remove it.