Firekeep documentation

Architecture

Firekeep is two halves. A server you run once, and a client kit installed on each member's machine that wires your agent runtimes into it.

Server services

Backed by three datastores in the same stack—Neo4j (knowledge graph), Qdrant (vector embeddings) and Redis (cache, queues, streams)— plus Ollama for local model inference.

Client kit

Installs to ~/.firekeep and renders configuration for whichever agent runtimes you use — Claude Code, Codex, Kiro and OpenCode are configured together (Claude Desktop too, when the app is installed), and any other MCP client can be added with firekeep install --runtime generic. It provides the MCP gateway your agent talks to, plus lifecycle automation where each runtime's hook surface allows it — a generic client exposes no hooks, so it gets the MCP tools and instructions on connect but not the hook lifecycle. The day-to-day section below names the current differences explicitly.

Dexes run client-side. A dex has to be local to what it indexes, so Symdex ships as a stdio MCP server on your machine rather than in the server stack, and Docdex reads your folders from there too. Which ones run is a registry on that machine — Dexes and documents. The Decision Board is client-side as well: it opens an ephemeral loopback browser surface and returns submitted answers to the waiting agent.

Capability map

Firekeep joins durable memory, working context, code intelligence and agent coordination. The boundaries below are part of the product: it records what agents explicitly send and automates only the lifecycle events each client exposes.

Symdex local code intelligence

Symdex parses your working tree locally with tree-sitter and gives supported agents focused codebase context through MCP. It is the first dex — a domain index that gives your Keep understanding of one domain. Its wheel installs with the client kit; whether its tools appear is a registration, and on a fresh machine that is one command: firekeep dex add symdex. A machine that already had Symdex keeps it across the update. See Dexes and documents.

The built-in parsers cover Python, JavaScript, TypeScript, Go, Rust, Java, PHP, C, C#, Ruby, Kotlin and Swift. Depending on the language's syntax, the index captures functions, classes, methods, types, constants, routes and their relationships. Thirty tools are available by default for symbol lookup, search, callers, architecture, impact and related context; eight heavier analytics tools are optional.

Symdex can serve symbol-level context when that is sufficient and include broader file context when an edit needs it. Firekeep's code-and-memory tools can also cross-reference the current code with decisions, fixes and change history recalled from earlier sessions.

Targeted symbol benchmark

The repeatable benchmark compares the stable response from a verified Symdex symbol lookup with reading that symbol's entire containing file. It uses one pinned public repository per supported language and 30 deterministic, file-balanced functions, methods, classes or types from each repository. Test, fixture, example and benchmark paths are excluded. No generation model or subjective judge is involved.

The primary result is the mean of all 360 per-lookup reductions, with equal samples per language and file-balanced selection within each project. Token counts use the cl100k_base encoding; o200k_base produces a similar 54.54% result. Every indexed file and returned source was also checked byte-for-byte against its pinned Git blob, verifying the requested code was returned exactly. The median reduction was 78.42%; 58 of 360 lookups used more tokens because the serialized tool response can exceed an already small source file. The benchmark measures direct known-symbol retrieval against a whole-file baseline.

Mixed-task Click benchmark

A separate archived benchmark asked 20 comprehension, navigation and modification questions about Click, with three generated answers per question and an LLM judge. Across the 20 unique context comparisons, Symdex consumed 23.31% fewer total context tokens. Its judged-accuracy point estimate was 4.42 versus 4.45 for raw-file context.

Judged accuracy was comparable across both conditions. Modification questions consumed more context because the tested builder combined raw files with structural analysis.

Working-state restore benchmark

When an agent's context window is compacted, it restores its working state from the session server. That restore returns the whole session document — plan, decisions, file knowledge, progress and scratchpad — and still does by default. An agent may instead hand back an opaque cursor and receive only what changed since it last looked. This benchmark measures the difference between those two responses. No generation model or subjective judge is involved; token counts use the cl100k_base encoding.

This is a per-restore reduction, not a per-request one. A delta is returned when an agent asks to restore its working state, which happens after a context compaction rather than on every turn.

Per-session reductions ranged from 0.8% to 67.4%, and the variation is structural. Scratchpad entries are stored without per-entry timestamps, so a delta always returns them in full; the same applies to proactively recalled memories, which are replaced wholesale rather than appended. Scratchpad alone accounted for 14.1% of all measured session tokens. Of the reduction, 80% comes from filtering decision, progress and file entries and 20% from omitting an unchanged plan.

The dataset is 26 real sessions from one operator on one machine. A separate check against a live deployment on 2026-08-01 reduced one session's restore from 12,122 to 4,977 characters.

The delta is opt-in. An agent that never sends a cursor receives byte-identical output to before, and six independent conditions — an absent, unparsable, wrong-session, stale, unreadable or unanchored cursor — each return the complete document rather than a partial one. Where the mechanism can be wrong, it returns too much rather than too little. A restore that omits content states what it withheld and how to retrieve it, so an agent reading a delta cannot mistake an omission for an absence.

Requirements

Server

• Docker and Docker Compose v2 with linux/amd64 container support — use an x86-64 Linux server or VPS, or Docker Desktop with amd64 support on Windows or Mac (on Windows, run setup under WSL2 or Git Bash)
• 2 x86-64 CPU cores minimum
• Git
• 16 GB RAM recommended for the default stack
• No open ports required — a default install binds to 127.0.0.1

Client

• Linux — CI cold-installs the published one-liner on seven distros every run: Ubuntu, Debian, Alpine, Fedora, Rocky, Arch and openSUSE. glibc and musl both work; Alpine is there to prove the musl path rather than to pad the list.
• Windows — PowerShell. CI runs the client suite and executes install.ps1 on a Windows runner.
• macOS — supported by the same bootstrap and its toolchain is built for it, but it is not in the CI matrix: our lab runs in Docker, which cannot host macOS. We test it by hand, not on every commit.
• Nothing preinstalled — the bootstrap fetches its own pinned toolchain
• Installing from a source checkout instead needs a system python3 >= 3.10

Licensing

Firekeep is one product: one client, one server, one capability set. There are no editions and no feature gates — the tier answers who governs the Keep, not which features you get.

The source is available under the Business Source License 1.1. Self-hosted use is free for self-hosted internal use is free for individuals and teams while Firekeep is in early access — any number of members, with unlimited agents, terminals and devices. Production use outside that grant requires a commercial licence. Each release converts to Apache-2.0 four years after publication.

There are no licence keys and nothing to activate. Every install is the complete product; the licence terms are the only boundary.

The terms also carry a published expiry: each release’s licence converts to Apache-2.0 four years after that release first ships. What you deploy today has a dated path to a permissive licence built into it.

Installing Firekeep

One bootstrap command per platform. It asks two required questions — who you are, and where your server is — then offers a skippable prompt for another MCP client. Standing up the server is one of the answers, not a separate procedure. There is no registry account and no licence token.

The bootstrap brings its own pinned Python toolchain and checksum-verifies everything it downloads before running it. Nothing has to be installed first — no system Python, no Node.

Three shapes, one command

Firekeep is a server you run once and a client kit on each member's machine. The same one-liner installs either or both; your answer to its server question decides which. Skim this, then read the walkthrough below.

Both and Server only are the same install with one difference — whether the box that built the server also becomes a client of it. Current server images target linux/amd64, so use an x86-64 Linux host or Docker Desktop with amd64 support on Windows or Mac (on Windows, run setup under WSL2 or Git Bash). The detail for each answer follows.

The two required questions

After these required questions, the installer offers one skippable prompt to add another MCP client and optionally manage its rules file. The four shipped adapters do not depend on that prompt.

The identity default is your OS username. It is kept as a question because the username is a good default and a poor answer — on a server it is often root, and every memory, session and replay event this machine writes is attributed to whatever you say here.

Answer 1 — the server provisions itself

It asks nothing further. The host address is detected (ip route get, falling back to 127.0.0.1) and the Neo4j password is generated. Both are overridable for the cases that need it — a NAT'd host or floating IP, a restored backup, a policy-managed secret — with --ip and --neo4j-password, or the FIREKEEP_VPS_IP and FIREKEEP_NEO4J_PASSWORD environment variables for unattended provisioning.

It downloads and checksum-verifies a source-free deployment bundle, pulls the public Firekeep images and starts the stack. When the stack is up, the machine enrolls itself through a join code minted locally over loopback, so firekeep doctor reports a connected server straight away — no dashboard, no SSH tunnel, no copied key. firekeep init --no-self-enroll opts out, which is what CI runs and what a golden image wants.

Server only — the stack, with nobody enrolled

A build host, a CI runner or a golden image should stand the stack up but not become a client itself. That is the same provisioning as answer 1 minus the self-enrollment:

From a source checkout or an unpacked release bundle, the direct equivalent is bash install.sh — add --pull to run the published images instead of building from source. Either way the stack comes up unenrolled; there is no client on this box and nothing is attributed to it.

Enroll machines against it afterwards exactly as below: hand each one the printed FIREKEEP_JOIN=… one-liner, or mint a code on the server with deploy/firekeep-admin invite --agent <name>. See Connecting a device.

Adding a second machine

The server prints a ready-to-paste command for the next machine. Run it there:

Same one command, with the code supplied up front, so that machine is not asked where the server is. A stock server answers only on 127.0.0.1, so the code carries an SSH route and firekeep join opens the tunnel itself using the SSH access you already have. The code is single-use and expires.

For every machine after that, mint another on the server with deploy/firekeep-admin invite --agent <name>, or use Dashboard → Devices → Add device.

The dashboard, and the two credentials

The dashboard is at http://127.0.0.1:8040/ on the server itself, and over the same tunnel from a machine that joined through a code. The browser asks for a login: username admin, with the password the installer wrote once to dashboard/.htpasswd.cred on the server at mode 0600 — read it once, then delete the file.

That is a separate credential from the admin API key. The admin key is an nxs_ token you send as an X-API-Key header to the Cortex API; the dashboard login will not accept it, and the dashboard password will not authenticate an API call. Join codes issued from the dashboard are single-use and valid for 24 hours.

While the models download

The install does not block on the ~3.3 GB embedding-model pull. The command returns as soon as the stack is up and the pull continues behind it. Until it finishes, memory writes return status="partial": stored and queued for backfill, but not yet findable by search. firekeep doctor shows an embeddings warning row saying exactly that, and docker compose logs -f ollama-pull shows progress. Use bash install.sh --wait-for-models if you would rather the install block until the pull is done.

Only the four Firekeep service images are published. Neo4j, Redis, Qdrant, Ollama and the nginx that serves the dashboard are pulled by your own Docker daemon from their upstream registries — Firekeep never redistributes them.

As a developer — build from source

From a checkout of the repository you have been granted access to:

A source checkout builds the Firekeep services locally. Add --pull only when deliberately testing the published-image path.

What the server installer does

• Checks for Docker and Compose v2, installing Docker if absent
• Asks nothing — it detects the host address and generates the Neo4j password, writing a validated .env at mode 600
• Generates a vault encryption key
• Mints API keys and prints an admin key exactly once
• Pulls public images or builds source images, then starts the complete stack
• Enrolls the machine it is running on, and prints a ready-to-paste command for the next one

Your first authenticated call

A fresh install is closed by default in two independent ways.

Both are deliberate. A fresh install answers only on the host itself and requires a key on every protected route — widening either is an explicit operator decision.

Server configuration

Everything lives in .env beside the compose file. The settings that actually change behaviour:

The client kit

The same one command from Installing Firekeep, seen from the client side: what the bootstrap does on a bare machine, and how to re-run parts of it. No system Python or Node required.

What the bootstrap does

1. Resolves the version and fetches that version's checksum manifest once.
2. Verifies before use. Both a mirrored toolchain and the client wheel are checksum-verified against that manifest before either is executed. The wheel is fetched to a local file and installed by path — never by URL, which does no hash checking, and never by name.
3. Installs the kit into ~/.firekeep with its own standalone Python.
4. Asks two required questions — your agent identity, and where your server is — then offers a skippable prompt for another MCP client. The install walkthrough shows the menu and what each answer does.
5. Acts on the answer: provisions a server here, redeems a join code, records an existing server, or stops and leaves the rest to firekeep doctor.
6. Renders every shipped adapter for Claude Code, Codex, Kiro and OpenCode — Claude Desktop too, when the app is installed — and, with firekeep install --runtime generic, prints a paste-in snippet for any other MCP client.
7. Installs both dex wheels, Symdex and Docdex, checksum-verified like everything else. Turning one on is separate and is yours: firekeep dex add symdex. An existing install keeps whatever it already had — see Dexes and documents.

Device credentials

However a machine joins, the client creates its credential locally, redeems the code once and writes a single server connection. Device credentials default to 90 days; firekeep doctor warns during the final 14 days, and a new join code rotates the device onto a fresh credential.

From a source checkout

./install installs the kit and renders adapters. firekeep install run from that environment re-renders adapters only — it skips the package install, because the code it would install is the code already running.

Use firekeep install --runtime <name> only to repair or re-render one adapter. A normal install prepares all four supported clients together. firekeep install --runtime generic --agents-md <path> adds any other MCP client: it prints the gateway’s MCP-server JSON snippet to paste into that client, and — when --agents-md is given — manages a marker-delimited instruction block in that rules file. The install wizard also offers this as one skippable question (“Also use an MCP client we do not ship an adapter for? Paste its rules/AGENTS.md path, or Enter to skip”). The generic tier gets the MCP tools and instructions on connect, not the hook lifecycle.

Firekeep Studio

One desktop workspace for Codex, Claude Code, Kiro CLI and Grok. Choose the primary agent, bring in fresh review, and run evidence-backed Missions without switching apps.

Latest release notes Published checksums Studio source

First run

1. Choose a workspace. Select the project folder every runtime should use. Studio remembers the choice locally; Missions require an explicit workspace.
2. Choose the primary agent. Pick Codex, Claude Code, Kiro CLI or Grok. The primary leads the conversation until you switch it.
3. Connect the provider when needed. Open Runtime Center from the primary picker. It shows account, connection, review and Keep status for every supported runtime.
4. Check readiness, then work normally. Type /doctor, resolve any setup item it names, and send your first prompt. Type / for live command completion.

Useful Studio commands

Run a verified Mission

Give the Mission a clear goal, add the project’s real acceptance command, then run it:

Studio confirms the workspace, permission mode, repair limit, token guard and commands before execution. Checks drive bounded repair, reviewers stay independent, and you make the final call.

Desktop updates

Use /update status or /update check at any time. Windows verifies and downloads ready updates in the background, then offers Restart to update. On macOS, Studio opens the latest universal DMG for a manual replacement.

Connecting a device

Every path here is the same mechanism: a single-use join code. It identifies the server and the enrollment ticket; the client chooses its own credential and stores one connection. What differs is only where the code comes from.

SSH shortcut for operators

An operator who already has shell access can use firekeep connect. It issues a single-use code over SSH and then calls the same join path locally:

Restart your agent session afterwards so it picks up the newly registered MCP servers.

CLI reference

Start with doctor

When anything is wrong, this is the first command to run — it checks the whole chain rather than one link.

firekeep doctor --report additionally sends an anonymous summary to firekeep.ai — the name and pass/warn/fail status of each check, plus your client version. Nothing else: not the messages doctor just printed, not a file path or hostname, not an IP address. This is off unless you type the flag — plain firekeep doctor never leaves your machine. See the privacy notice for exactly what is logged.

A client with no server

If you answered 4 at install, or the server never came up, doctor leads with the routing row rather than four identical connection errors:

On a machine that does have a server configured, the same row names the host that is not answering instead. Note that the third suggestion attaches to a server that is already installed on that box — see Connecting a device.

Embeddings still warming

A warn row on a freshly installed server is expected and needs no action — it is the model pull finishing:

Dexes and documents

A dex is a domain index that gives your Keep understanding of one domain. Three ship today — Symdex for code, Docdex for documents, Maildex for email — and a registry decides which of them runs on this machine. Since client 1.2.0 a fresh install registers Symdex and Docdex out of the box; Maildex registers itself when you connect a mailbox.

firekeep dex — what is turned on

Registration gates activity, not installation. All three wheels arrive with every release and are checksum-verified by the installer; add downloads nothing and remove uninstalls nothing. The only thing that changes is a line in ~/.firekeep/dexes.json, which decides whether the gateway mounts the dex's tools and whether its background work runs. Both commands are idempotent, and both take effect on the next agent session — the gateway reads the registry once, at startup.

firekeep docdex — the folders it may read

Docdex extracts .md, .txt, .pdf, .docx, .html/.htm, .eml and conversation-shaped .json (AI-chat exports with role-labeled turns); anything else is counted as skipped. The extracted text is ingested into your Keep's corpus and surfaces through ordinary memory_recall in your own sessions — there is no new recall surface and no MCP server. Deleting a file locally deletes its replica on the next sync, retried until the server confirms it.

These four commands work whether or not the dex is registered: registration gates the background sync and the doctor row, never a person's ability to say which of their own folders the Keep may read. There is deliberately no agent-callable tool for choosing a folder — that tool is absent, not guarded.

When a sync happens

With docdex registered and at least one source, a stale source is picked up in the background at session start on runtimes that expose a hook for it. It is detached from the session, so a cold scan never delays a session opening.

Opt out with FIREKEEP_NO_AUTO_SYNC=1 or [docdex] auto_sync = false in ~/.firekeep/config. Personal mode suspends syncing entirely — the trigger does not fire, and a run already in flight stops between batches.

Caps

All env-overridable; an unparseable value falls back to the documented default.

firekeep maildex — mail, read-only

Maildex connects a mailbox over IMAP and indexes recent mail into the same recall — always private to you, even on a shared Keep; there is no --shared for mail. firekeep maildex add imap.example.com you@example.com prompts for an app password and registers the dex automatically; firekeep maildex sync, list and remove work like their Docdex counterparts.

Read-only is structural, not promised: every mailbox open is IMAP EXAMINE and every fetch a PEEK — the wheel contains no send, move, flag or delete capability anywhere, and a build-time guard fails if one is ever added. The app password is stored in the server's vault under your identity — never on the client's disk — and is deleted when you remove the account. Defaults: INBOX and Sent, the last 90 days of mail, then incremental syncs.

All three dexes report to firekeep doctor, read from disk with no server call, so the rows are still there when the server is the thing that is broken:

last sync reports the stalest source, not the freshest: a row saying "just now" because one folder of five synced would hide the four that did not.

Day to day

The core MCP capabilities work through every shipped adapter — and through any other MCP client, installed with firekeep install --runtime generic. Lifecycle automation varies because each client exposes different hook surfaces; a generic client exposes none, so it gets the MCP tools and instructions on connect but not the hook lifecycle.

Automation by client

These differences affect convenience, not access to the underlying MCP capabilities. Every supported client can call the same server tools when its agent chooses to do so.

What your agent calls directly

Firekeep exposes its server capabilities through one local gateway, with Symdex and Decision Board running client-side. The tools that matter in ordinary work include:

The knowledge lifecycle, on autopilot

The knowledge base maintains itself without deciding anything on its own. What runs automatically: recorded session outcomes and explicit useful or not-useful feedback can nudge recall ranking, though current outcome discrimination is limited; sessions whose agent crashed or walked away are closed out after three days of silence so failures count instead of vanishing; close restatements supersede what they restate; stale knowledge ages into a recoverable archive.

What is deliberately proposed, never auto-applied: when two unconfirmed memories contradict each other, neither is dropped — both stay recallable, visibly marked as contested, until a human picks a winner or rules that both are true in their own contexts. Draft skills, stale skills, procedure proposals and contested pairs all queue in one review inbox on the dashboard's Autopilot tab, next to a digest of what changed in the last week. A memory's full evidence — provenance, usage, confirmations, feedback, outcome efficacy, disputes and lineage — is one read away, so every ranking has a visible why.

The instruction layer is measured too. The same tab's Living Instructions table scores each instruction Firekeep gives your agents — recall before answering, record as you go, declare consequential actions — against what sessions actually did, computed deterministically from the replay record with the caveat built into the response: compliance measures behavior, not whether the behavior helped. Agent-drafted instruction rewrites under human approval, validated by A/B across sessions, are roadmap — not shipped.

The dashboard

Served on port 8040. Because the stack binds to loopback, reach it through the tunnel connect established — at http://127.0.0.1:8040/, not the server's own address.

Governance, trust & private documents

Three capabilities that landed recently. Each is scoped honestly here — what it enforces, what it only reports, and what is still being built.

Enforced Runbooks

A skill is advice text until something watches whether its steps happen. Give a skill's steps command matchers and it becomes a runbook — and a human, never an agent, can arm it with an enforcement mode. Agents may propose a runbook; only a human with an admin key arms it, on a route the ordinary skill-edit path cannot reach.

Illustrative — the three human-armed enforcement modes.

• advise — a matched command is annotated, and proceeds.
• require_ack — it is challenged, and proceeds only after an audited acknowledgement with a recorded reason.
• block — it is stopped.

A command counts only when it actually ran and succeeded. Evidence commits in two phases: permission time writes a pending record, and only a matching exit status of zero commits it. A deploy that crashed never scores as a completed one.

Block fails closed. The client honours an allow only when the server's answer carries the marker it appends on a genuinely evaluated path — so a reachable but broken server reads as a block, not as an authenticated allow. Every lookup and permit is scoped to the verified workspace; the self-reported agent_id is a label, never the boundary.

Every enforcement event an operator would triage — a block fired, a challenge acknowledged with its reason, a matched command that ran and failed — lands in a per-workspace deviation ledger, surfaced on the dashboard's runbook cards and the Autopilot inbox. It stores the command's hash, never its text.

The Trust Ledger

Agents already declare consequential actions through the gateway: what they are about to do, how sure they are, and afterwards what actually happened. The Trust Ledger turns that stream into a per-agent employment record — how much each identity declared, how often it reconciled the outcome, how well its stated predictions matched reality, and how many of its own actions it later marked failed.

Illustrative — not a live capture. Components only; there is deliberately no single trust score.

It reports; it never gates. There is no headline trust number, on purpose — a composite gets treated as a gate, and a self-reported identity is the wrong thing to gate autonomy on. Turning this into earned autonomy is a separate, later piece of work; round one is the honest measurement, on the dashboard's Autopilot tab beside the compliance table.

Member-private documents

Memory on a shared server is a team asset — but not everything you want an agent to recall should be. Firekeep's document memory carries a per-folder visibility setting, and the default is private to you, even on a shared Keep. Private content surfaces through ordinary memory_recall in your own sessions and nowhere else.

The enforcing half — server-side tenancy — is shipped. One shared filter runs at every member-facing exit: a private chunk never appears in another member's recall, and a private source's name never appears in another member's listings or dashboard. Each document's chunks carry their own identity, so deleting your copy of some text can never remove a teammate's identical copy, and a half-finished re-ingest never exposes a partial document — recall only ever sees a committed generation.

Personal mode

An escape hatch that makes Firekeep dormant for work you do not want it to record.

Hooks, the presence sidecar and Decision Board re-read the state and stop communicating immediately. An MCP shim that is already running evaluates hard bypass only when it starts, so restart the active agent after changing Personal mode. A restarted shim exposes zero Firekeep tools while the mode is on; restart again after turning it off to restore them.

Operations

Updating

What version am I running?

Every service answers /version without a key and without touching its dependencies, so it responds even when the things behind it are down.

Health

Removing Firekeep

firekeep uninstall removes only what the kit installed: the Firekeep blocks in each runtime's config (your own settings are left intact), the firekeep launcher and its PATH entry, and ~/.firekeep. It asks first; --yes skips the prompt. It never touches a server you set up — memory, sessions and the vault survive.

Backup & restore

The rule this feature exists to satisfy: you should never discover your backup story during the disaster. The Keep backs itself up automatically; your job is one command to keep an off-box copy, and one runbook if the worst happens.

Automatic nightly backups

Since server v1.0.3 the Keep backs itself up: a cold snapshot nightly at 04:30 server time (neo4j, qdrant and redis stop for the one-to-three minutes of archiving — a copy of a live store restores without error and is wrong), with per-file checksums in a manifest, retention of 7 nightly + 4 weekly, and the server's .env included so a bare-metal restore recovers vault secrets too. Model weights are excluded — docker compose up -d re-pulls them. A backup on the server's own disk still dies with the server, so the off-box copy is a pull to a machine you control (client 1.0.2):

Disaster runbook, retention details and the manual tools: docs/guides/backup-and-restore.md. The short version: fresh host → install.sh → copy the pulled backup over → deploy/restore.sh → docker compose up -d.

Restoring

Restore runs on the server host with the stack stopped — firekeep backup restore prints these steps with your machine's real paths filled in. On a brand-new host, run the installer first, then restore into it:

restore.sh restores the archived .env when present — with an explicit confirmation, never a silent overwrite — and firekeep doctor from any enrolled machine confirms the Keep is healthy afterwards.

Manual backups and recovery caveats

The nightly job wraps the shipped deploy/backup.sh, which you can also run by hand; it quiesces Neo4j, Qdrant and Redis before their files are copied, because a partial or hot filesystem copy can look valid while containing inconsistent graph, vector or auth state. A manual run archives the four base volumes (including Ollama's model weights) and — unlike the nightly job — does not copy .env.

Troubleshooting

Everything returns 401

Expected on a fresh install — AUTH_ENABLED=true is the default. Confirm the service is actually up with the keyless /health, then check that your client connection has an API key. firekeep doctor reports a missing or rejected key directly.

Memories save, but recall finds nothing

On a server installed in the last few minutes, this is the model pull, not a fault. The install stops blocking once the stack is up, and until the ~3.3 GB embedding model has finished downloading, writes return status="partial": the memory is stored and queued for backfill, but it is not searchable yet. Nothing is lost and nothing needs re-writing — the backfill makes it findable.

Confirm with firekeep doctor, which shows an embeddings warning row until the model is loaded, and watch it with docker compose logs -f ollama-pull. To avoid the window entirely on the next install, use bash install.sh --wait-for-models.

Connection refused from another machine

Also expected. BIND_ADDR=127.0.0.1 means the ports answer only on the host. Attach the machine with a join code rather than pointing it at an address: firekeep join fk_join_… if it already has the kit, or the FIREKEEP_JOIN=… one-liner the server printed if it does not — a code issued by a loopback-bound server carries its own SSH route. An SSH tunnel, private network or HTTPS reverse proxy of your own works too, as does the operator shortcut firekeep connect user@host --remote-dir ~/.firekeep/server. Pointing a client at an unbound public address simply times out.

If firekeep doctor instead reports this machine has a Firekeep client but no server to talk to, there is no server configured at all — see Start with doctor.

The dashboard says a service is unreachable

Check the service directly on the host with curl against /health. If that answers and the dashboard disagrees, the proxy in front of the dashboard is misrouting rather than the service being down.

Containers restart or get killed

Almost always memory. Check docker stats against the requirements above. The symptom is misleading: health checks keep passing while the process inside is killed and restarted.

The agent does not see the tools

MCP servers are registered at install, and a running agent session does not pick up new ones. Restart the session. If they are still missing, firekeep install --runtime <name> re-renders that runtime's configuration.

On Linux or macOS, if the gateway connects but exposes only firekeep_gateway_status, you are on client 0.1.37 — a resolution bug fixed in 0.1.38. firekeep update resolves it.

The Symdex tools are gone

Check firekeep dex list. An existing install is grandfathered across the update, but if that listing says available rather than registered, run firekeep dex add symdex — and note that it takes effect on the next agent session, not the current one. If it says registered (wheel missing!), the wheel did not land: re-run the installer, or firekeep dex remove symdex.

Documents never appear in recall

In order: is the dex registered (firekeep dex list); is the folder added (firekeep docdex list); has a sync actually run (last sync in that listing, or the docdex row in firekeep doctor); does the runtime have a hook surface at all — on Codex, Claude Desktop and generic MCP clients nothing syncs until you run firekeep docdex sync; and is personal mode on (firekeep personal status), which suspends syncing. A source shown as refused holds more indexable files than FIREKEEP_DOCDEX_MAX_FILES — narrow the folder or raise the cap.

Still stuck

Run firekeep doctor and include its output when you get in touch. It reports the whole chain — connection, auth, versions, permissions — rather than one link of it.