FAQ & troubleshooting
The first half is what people ask before they start. The second half is what actually goes wrong, and the exact change that fixes each one.
Before you start
Can I use this without paying for API access?
Yes. A token from a Claude subscription you already pay for is a
first-class path, not a workaround. Run
claude setup-token on your own machine and paste the
result into the wizard. The connection test names the models that
answered,
claude-haiku-4-5-20251001, claude-sonnet-5, in 1820 ms. An
API key works too if you prefer one.
Do I need the server at all?
No. The template plus Claude Code is the complete local product. Feed, approve, ask. That loop is three turns and about two minutes of agent time, with no server anywhere.
The server adds three things: every agent you run can reach the brain, review moves into a browser, and visibility tiers get enforced on the way out. If you do not need those, you do not need it.
What happens to my brain if I stop running the server?
Nothing happens to it. It is your git repository. The server clones it and reads it, and writes to it only through the approval queue, using credentials you gave it. Turn the server off and the brain is exactly where it was, readable by any editor and by Claude Code.
Why is the engine public if my brain is private?
They are two different repos, and that is the design. The server is open source so you can read what handles your notes. Your brain is a separate private repo of your own. Nothing about running this puts your content anywhere except the machine you chose and the repo you own.
Can I use it with something other than Claude Code?
For the server, yes. Any MCP client that speaks streamable HTTP works:
point it at /mcp/ with a bearer token. The REST API is
plain JSON over HTTP and needs no MCP at all.
The local-only loop is a different matter. It is built on Claude Code skills, so it wants Claude Code.
How much does a feed cost?
There is no published number here, because a feed run on a subscription token has no per-feed price to report. What your instance can tell you is exact: every token, every read and every agent run is logged and priced on your own dashboard.
Where it actually goes wrong
The setup page redirects to https and never loads
You are on plain http, and
SECURE_SSL_REDIRECT_ENABLED defaults on. Every request
301s to https, including the wizard that would let you
fix it. Set SECURE_SSL_REDIRECT_ENABLED=0 for a local
trial. Behind a real TLS proxy, leave it alone.
Nothing is listening on port 8000
Compose picks a host port for you, and it changes. One lab port
moved six times across rebuilds. Read it back rather than
assuming: docker compose port web 8000. Anything with
the port written down will eventually aim at a dead one.
A variable is set, and the app says it is not
An empty value counts as unset. Hosting panels leave a blank row
behind when you clear a field, and Compose passes every unset
${VAR} through as an empty string, so the two are
indistinguishable by design. Delete the line, do not blank it.
The token is valid and the push still fails
An approval can die on
remote: Write access to repository not granted … 403
with a token that is live and correct. A fine-grained token needs
Contents: Read and write and the brain
repo listed under Repository access. Miss the second and
it looks fine everywhere until a feed fails. Press
Verify on the write step, which asks the remote
the same question git push asks.
The new repo is empty
GitHub creates a repo from a template before it finishes copying
the files in. It was empty for 0.8 seconds. Point a server at it
inside that window and it clones nothing. Refresh until you see
CLAUDE.md, then continue.
Nothing happens after I paste a feed
Extraction starts on its own. There is no button to press, and
there is nothing to wait for beyond the agent finishing. A short
source took 50.3 seconds. If a proposal never appears, check
the Claude credential on the settings page, then
/ops/tasks/.
The server is serving an old version of my brain
There is no periodic pull. Three things sync the clone: the GitHub
webhook, the Pull from GitHub button on the health
page, and manage.py sync_brain. Without the webhook
the server keeps serving your brain as of the last manual pull,
indefinitely, and nothing warns you. Set the webhook up.
My agent says the brain is empty, and it is not
Check the key's tier first: POST /api/v1/ping reports
it. A key with no consumer profile reads as public,
and a public tier on a young brain is genuinely nearly empty. One
brain showed 2 entities at public and 7 at
agents-only.
If you run nested agents, also check which server answered. A
nested run can inherit MCP servers from your user config. Pass
--strict-mcp-config and you will know.
/readyz says 503 and the deploy will not go green
That is /readyz doing its job: it stays red until a
valid brain is cloned, which on a fresh install is until you finish
the wizard. Point your platform's health check at
/healthz instead, which answers as soon as the app is
up.
I locked myself out of my own ops UI
Behind a proxy, the address the app sees is the proxy, not the
caller. Every per-IP control then treats the whole internet as one
address, so an attacker's failed logins trip the lockout on the
address you share with them. Set
TRUSTED_PROXY_IP_HEADER and
TRUSTED_PROXY_IPS together, before you set
ADMIN_IP_ALLOWLIST. Setting one without the other
refuses to boot on purpose.
Still stuck?
The health page on your own instance is the fastest triage: it runs every check, sorts problems above everything else, and tells you the address the app actually observes. If the answer is not there, open an issue and include what the health page says.