Self-host Yaan

Before you start

• Docker, with Docker ComposeOn Windows and macOS, install Docker Desktop. On Linux, install Docker Engine and the Compose plugin.
• GitTo get the code.
• An Anthropic API key (optional)Without a key, you can browse the graph and use all graph tools. To ask new questions, you need a key.

Connect your tools

Each connector reads events into Yaan. Approved actions go back out as comments and messages. Connect one tool or all four. Put each value into .env.

Start the connectors

Switch Yaan from the demo to your own data. In .env, set YAAN_DATA_MODE=org. Your data then goes into its own graph, yaan_org. Nothing from the demo graph is mixed in.

Copy the example map, then edit it. Name your product and the channels Yaan reads. Each channel name starts with bug-, develop- or planning-. The prefix tells Yaan what to read from it.

Say who may read each source other than Slack: visibility: everyone, or visibility: members with a members list. Slack tells Yaan which channels are private and who is in them. Until a source says, Yaan shows nothing from it.

cp connectors.org.example.yaml connectors.yaml

Optional: list your people in people.yaml, with their role and their account in each tool. A role decides who may close or reopen an issue. Yaan adds everyone else the first time they appear.

Apply your settings, create your graph, and check the connectors:

docker compose --profile app up -d --force-recreate api
./yaan init
./yaan connectors status

Start the connectors. They run in their own container, which Docker restarts after a crash or a reboot:

docker compose --profile app --profile connectors up -d
docker compose exec worker yaan connectors health

An item a connector can’t ingest is kept, not dropped: yaan connectors dead lists them and yaan connectors retry replays them once you have fixed the cause.

Tip: Slack uses Socket Mode. You do not need a public URL. GitHub, Jira and Notion are checked every 30 seconds.

The first sync reads the last 30 days. To go further back, see what it would cost first: yaan connectors backfill --days 365 is a dry run; add --yes to ingest it.

Connect your AI client

Yaan gives its graph tools to any MCP client. Your client’s model does the reasoning. Yaan’s graph lookups cost no AI tokens. Yaan must be running.

claude mcp add --transport http yaan http://127.0.0.1:8000/mcp

[mcp_servers.yaan]
command = "docker"
args = ["exec", "-i", "yaan-api-1", "yaan", "mcp"]

{
  "mcpServers": {
    "yaan": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

Then ask, for example: “Which customers are waiting on a fix?” or “Anything break overnight?”

Keep it secure

Yaan is safe on your own computer with the default settings. Before other people can reach it, do these steps:

• Change the three database passwords. The example values are for local use only.
• Keep the ports on 127.0.0.1. Put an HTTPS proxy, for example Caddy or nginx, in front of Yaan.
• Tell Yaan the address of your proxy. Set FORWARDED_ALLOW_IPS. Then each visitor gets their own request limit.
• Set a daily AI spend cap. Use YAAN_DAILY_SPEND_CAP_USD.
• For a public demo, replay answers only. Set YAAN_LLM_CACHE_ONLY=1. Yaan then never calls the AI model for a new question. Also set YAAN_MCP_ASK=0.
• Keep the request limits on. The defaults limit questions per address, per day and in total, and limit how many answers run at the same time.
• Give each device its own token. Tokens expire after 90 days. yaan token list shows them with when each was last used; yaan token revoke "Name" --id <id> ends one, and every browser session signed in with it.

Architecture

Yaan is one service and one database. Both run on your server. Events come in from your tools, go through one pipeline, and become a graph in FalkorDB. Two parts read that graph: the answer agent, which answers questions, and the Change Sentinel, which watches for changes. Your team uses Yaan from the web app, from Slack, or from their AI client.