Multi-tenant markdown knowledge base with team-level RBAC and semantic search, exposed to Claude through MCP. See ARCHITECTURE.md.
cp .env.example .env # set NANACE_JWT_SECRET (openssl rand -base64 48)
make run # starts PostgreSQL + Qdrant, then the API on :8080The first start downloads the bge-small-en-v1.5 model (~130 MB) into
.fastembed_cache/.
- In Google Cloud Console create an OAuth client of type Web application
with redirect URI
http://127.0.0.1:8080/api/v1/auth/google/callback(use yourNANACE_PUBLIC_URL). - Set
NANACE_GOOGLE_CLIENT_ID,NANACE_GOOGLE_CLIENT_SECRET, and optionallyNANACE_GOOGLE_ALLOWED_DOMAINSin.env. - Open http://127.0.0.1:8080/auth/complete, sign in, and create a
personal access token (
readscope is enough for Claude).
Without Google, NANACE_DEV_LOGIN=true gives a session for any email:
curl -s -X POST localhost:8080/api/v1/auth/dev-login \
-H 'Content-Type: application/json' -d '{"email":"you@example.com"}'In the desktop app, choose Connect to Claude in the sidebar. It registers the bundled MCP server with Claude Code (all projects) and/or Claude Desktop, each with its own read-only token. Check Allow Claude to create and edit pages to let Claude save notes ("save this to nanace"). To set it up by hand instead, build the MCP server once:
cargo build --release -p nanace-mcpClaude Code, with a personal access token:
claude mcp add nanace \
--env NANACE_API_URL=http://127.0.0.1:8080 \
--env NANACE_TOKEN=nnc_pat_... \
-- "$PWD/target/release/nanace-mcp"Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"nanace": {
"command": "/absolute/path/to/target/release/nanace-mcp",
"env": {
"NANACE_API_URL": "http://127.0.0.1:8080",
"NANACE_TOKEN": "nnc_pat_..."
}
}
}
}Instead of NANACE_TOKEN you can set NANACE_TOKEN_FILE to a file that
holds the token (re-read on every request; keep it readable only by you), so
the token stays out of config files.
Against a development API you can use NANACE_DEV_EMAIL=you@example.com
instead of a token. NANACE_ORG_ID picks a default organization.
NANACE_ALLOW_WRITES=true (with a write-scoped token) adds the
create_context and update_context tools.
integrations/claude-code/skills/nanace is a Claude Code skill: /nanace PROJECT-2345 records what was done in the current session on the task's page
(appending a dated section, or creating the page). It treats each team as a
wiki: before writing it reads the team's Wiki: Schema page (page types, title
prefixes, templates, tags), and afterwards it updates the related Topic: page
and Wiki: Index. Wiki: pages are edited only by the teamspace owner (team
role admin): for the owner, a team without a schema is initialized from
schema-template.md and marked as the default for review; for anyone else the
skill creates no Wiki: page and ends with the lines for the owner to add to
the index.
It needs the write tools (Allow Claude to create and edit pages).
Install or update the MCP server binary and the skill, and connect Claude Code
to your server, with one command (run it again later to update). Point it at
your server with NANACE_API_URL; the default is http://127.0.0.1:8080:
macOS / Linux:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.sh)"
# with your server:
NANACE_API_URL=https://nanace.example.com \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.sh)"Windows (PowerShell):
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.ps1 | iex"
# with your server, in a PowerShell window:
$env:NANACE_API_URL = 'https://nanace.example.com'
irm https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.ps1 | iexWhat the installer does:
nanace-mcp: downloads it from the latest GitHub release (NANACE_VERSION=v0.1.3pins one), checks the.sha256, and installs it to~/.local/bin(Windows:%LOCALAPPDATA%\nanace\bin; override withNANACE_BIN_DIR). A.nanace-mcp.versionfile next to it records the release and checksum, so a re-run downloads nothing when the binary is current, updates it when a newer release exists, and repairs it when the file was changed. The replacement is atomic, so a running server is not affected. Published builds: macOS arm64, Linux x64/arm64 (glibc), Windows x64; on other platforms (for example Intel macOS) the binary is skipped — use the desktop app, which bundles it, orcargo build --release -p nanace-mcp.NANACE_SKIP_BINARY=1installs only the skill.- Skill: copies it to
~/.claude/skills/nanace(or$CLAUDE_CONFIG_DIR/skills/nanace) fromNANACE_REF(defaultmain). An older version is moved to~/.claude/skill-backups/first. - Claude Code connection (interactive, asks before changing anything):
connects Claude Code to the server at
NANACE_API_URL(defaulthttp://127.0.0.1:8080, for exampleNANACE_API_URL=https://nanace.example.com). It opens<server>/auth/complete, where you sign in and create a token with scopewrite, reads the token with hidden input, checks it against the API, and saves it to~/.config/nanace/claude-code.token(Windows:%LOCALAPPDATA%\nanace\claude-code.token; override withNANACE_TOKEN_FILE), readable only by you. If you belong to several organizations it asks which one to use (or setNANACE_ORG_ID). Then it runsclaude mcp add nanace --scope userwithNANACE_TOKEN_FILE, so the token is never in a config file or a command line. A re-run reuses the saved token, and does nothing when Claude Code already uses thisnanace-mcp(NANACE_RECONNECT=1connects again, e.g. after changing the server). If Claude Code runs another copy (such as the desktop app's, which Connect to Claude registers and the app updates), it asks before switching. Without a terminal, or withNANACE_CONNECT=0, it only prints the manual steps. New users need an account on the server and, to save pages, a team role ofwriterfrom an admin; the installer warns when that is missing.
To install the skill from a local clone instead of GitHub:
NANACE_BASE_URL="file://$PWD/integrations/claude-code/skills/nanace" integrations/claude-code/install.shAgents of teammates can ask each other questions directly: Claude Code on one laptop asks, Claude Code on another answers, after that laptop's owner agreed. The text travels between the two machines; nanace records who talked to whom, never what was said. Everything is off until it is turned on in three places.
-
The installation runs a network node.
nanace-p2p nodeis a relay that laptops behind NAT are reached through. It asks the server which peers may connect, on a listener that must not be public:# server NANACE_INTERNAL_BIND=10.0.0.5:9191 NANACE_P2P_NODE_SECRET=<openssl rand -base64 48> NANACE_P2P_BOOTSTRAP=/dns4/p2p.example.com/udp/4001/quic-v1/p2p/<node peer id> # node (print its peer id with: nanace-p2p peer-id) NANACE_P2P_KEY_FILE=/var/lib/nanace-p2p/node.key NANACE_P2P_LISTEN=/ip4/0.0.0.0/udp/4001/quic-v1,/ip4/0.0.0.0/tcp/4001 NANACE_P2P_EXTERNAL_ADDRS=/dns4/p2p.example.com/udp/4001/quic-v1,/dns4/p2p.example.com/tcp/4001 NANACE_INTERNAL_URL=http://10.0.0.5:9191 NANACE_P2P_NODE_SECRET_FILE=/run/secrets/nanace-p2p-node
-
The teamspace owner creates the page
Policy: P2P. Its first```yaml p2p-policyblock says who may message whom (by team role), the limits, and how freely requests may be accepted. The desktop app offers the template;Policy:andWiki:pages are edited only by the owner. -
Each person turns it on in the desktop app (Agents (P2P)): which teams, and whether to be asked for every request. After that, Connect to Claude gives Claude the
p2p_*tools.
Without the desktop app, the installer sets up the daemon as a service of
your user (launchd on macOS, systemd --user on Linux) and gives Claude
Code the p2p_* tools:
NANACE_P2P=1 NANACE_API_URL=https://nanace.example.com \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/felichita/nanace/HEAD/integrations/claude-code/install.sh)"It asks for a second token with the scope p2p and for the teams to take
part in. This daemon has no window to ask you about a request, so it answers
on its own within the policy: the team owner must list your account under
server_peers.users and set max_accept_mode: team. Windows has no such
mode yet; use the desktop app there.
To try it between two computers, run that command on both, signed in as two members of one team, then on each:
export NANACE_P2P_DIR=~/.local/share/nanace/p2p
nanace-p2p call whoami # peer id, org and team ids
nanace-p2p call find_peers '{"org_id":"<org id>","team_id":"<team id>"}' # the other computerand ask Claude on one of them to message the other (p2p_peers, p2p_ask);
the other's Claude reads it with p2p_inbox and answers with p2p_reply.
The owner sees the exchange, without its text, in the team's journal. From a
clone, NANACE_LOCAL_BIN_DIR=target/release installs binaries you built
instead of a release.
An agent without a person, in a container, runs the same daemon with the
team role agent and a p2p-scoped token:
NANACE_API_URL=https://kb.example.com
NANACE_TOKEN_FILE=/run/secrets/nanace-p2p.token
NANACE_P2P_DIR=/var/lib/nanace-p2p
NANACE_P2P_BOOTSTRAP=/dns4/p2p.example.com/udp/4001/quic-v1/p2p/<node peer id>
NANACE_P2P_KIND=server
NANACE_P2P_TEAMS=<org id>:<team id>:team
nanace-p2p daemonIts account must be listed under server_peers in the team policy. Keep
NANACE_P2P_DIR on a volume: it holds the peer key, and a new key on every
restart leaves a bound peer behind each time. nanace-mcp in the same
container gets NANACE_ALLOW_P2P=true, NANACE_P2P_SOCKET=$NANACE_P2P_DIR/p2p.sock
and NANACE_P2P_SECRET_FILE=$NANACE_P2P_DIR/ipc.secret.
Check a running daemon by hand with nanace-p2p call whoami.
What to know before relying on it:
- A request is delivered only when both daemons are online at the same time before it expires; there is no mailbox on the server.
- Secrets are blocked by pattern in both directions. That catches known formats, not every secret.
- Messages from other agents are data for the model, not instructions. That is stated to the model and cannot be enforced on it.
Conventions for summary pages and an example verdict agent are in
integrations/claude-code/p2p/. Design and threat model:
docs/adr/0001-p2p.md.
Requires Node 20+ and the Rust toolchain. With the API running:
make desktop-dev # npm install + tauri dev
make desktop-build # release bundle in apps/desktop/src-tauri/target/release/bundleSign in with Google (opens your browser) or, against a dev server, with any
email. Import Claude memory, in the sidebar or ⌘K, turns Claude Code's
memory files (~/.claude/projects/*/memory) into linked pages. The app stores a personal access token named "nanace desktop" in the
macOS Keychain (or the OS keyring).
The Docker workflow publishes the backend image for linux/amd64 and
linux/arm64 for every v* tag (pull requests only build it):
docker pull ghcr.io/felichita/nanace-server:latest # or :0.1.2, :0.1The image runs nanace-server as a non-root user on port 8080 and has the
embedding model baked in, so it starts without internet access. It also has
nanace-p2p: run the P2P network node from the same image as a second
container with the entrypoint nanace-p2p and the command node (key on a
volume at /var/lib/nanace-p2p, port 4001 TCP and UDP). It does not
contain nanace-mcp: Claude runs that on each user's machine (it ships with
the desktop app and the release archives) and points it at the server. Configure it with the same environment variables as
.env.example (DATABASE_URL, QDRANT_URL, NANACE_JWT_SECRET,
NANACE_PUBLIC_URL, ...); PostgreSQL must give it a non-superuser role (see
deploy/postgres/init.sql). Probes: GET /livez (liveness: the process
answers, no dependencies touched) and GET /readyz (readiness: PostgreSQL and
Qdrant answer; /healthz is the same).
Build it locally with docker build -t nanace-server ., or run the whole
stack (API server, PostgreSQL, Qdrant) with Docker Compose:
make up # docker compose --profile app up -d --build; settings from .env
make logs # follow the server logs
make down # stop it (data volumes are kept)With the P2P network node as well:
echo "NANACE_P2P_NODE_SECRET=$(openssl rand -base64 48)" >> .env
# the node's peer id (creates its key on the first run)
docker compose --profile p2p run --rm --no-deps p2p-node peer-id
# add to .env, with the address agents reach this machine at:
# NANACE_P2P_BOOTSTRAP=/dns4/p2p.example.com/udp/4001/quic-v1/p2p/<peer id>
# NANACE_P2P_EXTERNAL_ADDRS=/dns4/p2p.example.com/udp/4001/quic-v1,/dns4/p2p.example.com/tcp/4001
# NANACE_HOST_BIND=0.0.0.0 # the node must be reachable from outside (this also publishes the API port)
make up-p2pThe server listens on 127.0.0.1:8080; set NANACE_HOST_BIND=0.0.0.0 to
share it on your network.
- Logs:
NANACE_LOG_FORMAT=jsonwrites one JSON object per line, for Loki or ELK (the default istext). Request logs carry the path only, never query strings. - Metrics:
NANACE_METRICS_BIND=0.0.0.0:9090serves Prometheus metrics on/metricson that separate listener, so the public ingress never exposes them. Docker Compose serves them on127.0.0.1:9090.nanace_http_requests_totalandnanace_http_request_duration_seconds, by method, route pattern and status;nanace_embedding_duration_seconds, bypassageorquery.
By default the server upgrades the database when it starts:
- it applies the SQL migrations;
- it runs the application upgrades written in Rust (for example backfilling derived data);
- if
NANACE_EMBEDDERnow selects a different model, it reindexes.
On Kubernetes, run that as a separate step instead (an init container, a
Job, or a Helm pre-upgrade hook) and start the pods with
NANACE_RUN_MIGRATIONS=false. They then refuse to start on a database that
is behind or ahead of them:
nanace-server migrate --check # report only; exit status 1 when something is pending
nanace-server migrate # apply, then exitTo rebuild the vectors from PostgreSQL, for example after moving to a new or
empty Qdrant or changing the embedding model, run the reindex command. It
recreates each organization's collection; search for that organization is
incomplete until it finishes:
docker compose --profile app run --rm server reindex # all organizations
docker compose --profile app run --rm server reindex --org <id> # one organization
cargo run -p nanace-server -- reindex # from source, with .env
``` Unverified email login stays off in Compose unless
`NANACE_COMPOSE_DEV_LOGIN=true`.
## Releases
Prebuilt downloads are on the GitHub Releases page:
- **Desktop app:** macOS (Apple silicon and Intel), Windows x64, and Linux
x64/arm64 (AppImage, deb, rpm).
- **Server and MCP archives:** Linux x64/arm64, macOS arm64, Windows x64.
To publish a release, push a version tag:
```bash
git tag v0.1.0 && git push origin v0.1.0The Release workflow builds everything on native runners, uploads it to a
draft release, and publishes it when every build succeeds. Builds are not
code-signed yet.
make check # fmt, clippy -D warnings, unit tests
make test-integration # API, RLS and MCP tests (nanace_test DB + qdrant-test)
make test-model # real embedding model test
make desktop-check # desktop: tsc, vitest, clippy, Rust testsLicensed under the Apache License, Version 2.0. Copyright 2026 Fedor Nikolaev.