Get started

The happy path: from download to your first task

One straight line from a fresh Windows PC to a working Fanad you can text. No prior setup, no command line required — download, click through, done.

Fanad runs on your own machine. This guide walks the easiest route end to end: install the Windows app, give it a brain (a hosted model to start, or a private local one), run the one-time setup, hook up a Telegram bot, and — if you want it on your phone from anywhere — put it behind your own domain. Every step below is optional to skip except installing and giving it a brain; take the ones you need and ignore the rest.

Start at step one Full manual Cheat sheet

Just want to try Fanad?

You don't have to install anything to see what Fanad is — start with the live demo. This page is for the next step: running your own private copy on your own machine.

0 · Before you start

You'll need a Windows 10 or 11 PC and about 10–15 minutes. No admin rights, and nothing gets added to your system PATH — the installer is fully self-contained. A Telegram account is optional (only if you want the phone bot); the web app works on its own.

The one real prerequisite

Fanad thinks with an AI model that you point it at, and the one thing that trips up a fresh install is not having that model ready. Step 2 sorts it out: most people start with a quick hosted model (one API key — fast, cheap, works on any machine), and you can move to a fully private local model whenever you're ready. You only need one.

1 · Download & run the installer

The easiest start is the Windows installer — it bundles its own Node runtime, so there's nothing to install first.

  1. Go to the Releases page at github.com/NTBooks/Fanad/releases and download the latest FanadSetup-<version>.exe.
  2. Double-click it. It isn't code-signed yet, so Windows SmartScreen shows an “unknown publisher” warning — click More info → Run anyway. (You only see this once.)
  3. Let it install. It goes under %LOCALAPPDATA%\Fanad for just your user — no admin prompt, its own private Node runtime, nothing added to PATH.
  4. It adds two Start-Menu shortcuts: Fanad Setup and Start Fanad Server. When install finishes, the setup wizard opens on its own (that's step 3).

Uninstalling later keeps your data and your encryption key — they live in data\ and .env beside the app, and the uninstaller tells you where.

Prefer the command line?

On any platform with Node 24+ you can instead run npx github:NTBooks/Fanad — it copies the app into ./fanad, opens the same wizard, then installs, builds, and starts. The Windows installer above needs none of that.

2 · Give Fanad a brain

Fanad needs an AI model to do its thinking, and you point it at one you choose. There are two ways, and you only need one. For most people starting out, a hosted model is the easiest and fastest; running one locally is the fully private route you can grow into.

Recommended for most: a hosted model (OpenAI or Gemini)

It's fast, cheap, and works on any computer — no graphics card or powerful machine required. You paste one API key and you're done. The trade-off: your notes are sent to the provider to be processed (it's still your key and your account). For most people that's a fair deal for how much smoother it makes the first run — which is why it's the recommended starting point.

  1. Pick OpenAI or Google Gemini. Either one covers both halves of Fanad's brain — chatting and remembering — from a single key.
  2. Create an API key:
    • Gemini — Google AI Studio → Get API key. Has a free tier, so it's the cheapest place to start.
    • OpenAI — platform.openai.com/api-keys → Create new secret key. Pay-as-you-go, but the fast model below costs fractions of a cent per message.
  3. You'll paste that key into the setup wizard's AI brain step (step 3): choose the same provider for both chat and embeddings — picking a cloud provider flips the cloud gate on for you — and leave the model fields blank for the cheap, fast defaults (gpt-4o-mini for OpenAI, gemini-2.5-flash for Gemini).

For full privacy — and where things are heading: a local model (LM Studio)

Run the model on your own machine and nothing ever leaves your box — the purest version of Fanad's privacy promise. It asks more of your hardware (a recent GPU, plenty of RAM, or Apple Silicon) and can feel slow without it, which is why it isn't the default today. But local models keep getting better and lighter, so this is the route to grow into — and you can switch over any time. LM Studio is the simplest way in.

  1. Download and install LM Studio from lmstudio.ai.
  2. In its search, download two models: a chat model (something small like Llama 3.2 is fine to start) and an embedding model (e.g. nomic-embed-text).
  3. Open the Developer tab, load both models, and click Start Server. It listens at http://127.0.0.1:1234 — exactly where Fanad looks by default. In the wizard, just leave the provider on LM Studio.
Two models, not one

A local setup needs both a chat model and an embedding model loaded: Fanad uses the chat model to talk and the embedding model to remember and recall by meaning. If only the chat model is loaded, capture and recall will error.

Not sure which to pick? Start hosted — it's the smoothest first run — and move to a local model later from web Settings whenever you want. You're never locked in.

3 · Run the setup wizard

The wizard opens in your browser right after install (or launch it any time from Start Menu → Fanad Setup). It's a one-time form that writes your config file; it runs only on your own machine (127.0.0.1:8899) because it collects secrets. Work down the four sections:

  1. Server — the Web UI port. Leave it at 8787 unless that's taken.
  2. Telegram bot — optional. Paste a bot token here if you already have one, or leave it blank and add it later (step 5 shows how to get one).
  3. AI brain — going hosted (the usual choice)? Pick OpenAI or Gemini for both chat and embeddings and paste the key from step 2, leaving the model fields blank for the fast defaults. Running local instead? Leave LM Studio selected for both and the fields blank.
  4. Encryption — an encryption key (KEK) is generated for you. Don't clear it.

Then click Save & finish setup. That writes your .env file.

Save your key

Keep a copy of that .env (or at least the KEK) somewhere safe, like a password manager. It encrypts every secret Fanad stores — bot tokens, API keys — and it's the only thing protecting them if the machine is ever lost.

4 · Start Fanad & open the app

From the Start Menu, click Start Fanad Server. It launches, then open your browser to:

http://localhost:8787

You'll land in the Fanad web chat. Say hello — type anything and it becomes your first task. That's the whole grammar: a statement files a task, a question runs a command.

By default the web app has no login — it trusts whoever's at the keyboard, which is right for a personal machine. If you'll reach it over a network, turn on web login first (see step 6).

5 · Get a Telegram bot (BotFather)

Want Fanad in your pocket? Give it a Telegram bot — then you just text yourself. It takes a couple of minutes, and no public URL or open port is ever needed (the bot reaches out to Telegram, not the other way around).

  1. In Telegram, open a chat with @BotFather and send /newbot.
  2. Give it a display name, then a username ending in bot (e.g. my_fanad_bot).
  3. BotFather replies with an HTTP API token like 123456789:AA…. Copy it.
  4. In Fanad, open web Settings → Telegram, paste the token, and add your own Telegram @username to the allow-list. Save. (You can also paste the token into the wizard's Telegram field back in step 3 — either works.)
  5. Message your bot and send /howto to begin.

Access is fail-closed: the first person to message the bot is claimed as the owner, and everyone else stays silent until you allow-list or vouch them. Tokens are stored encrypted with your KEK.

6 · Reach it from anywhere (optional)

The Telegram bot already works from anywhere. This step is only for reaching the web app in a browser away from your desk. Three ways, easiest first.

On your home network — the local IP

Fanad listens on every network interface, so any device on the same Wi-Fi can already reach it. Find your PC's local IP with ipconfig (look for the IPv4 address, e.g. 192.168.1.42), then on your phone or laptop open:

http://192.168.1.42:8787

Turn on a login first

The web app has no password by default, so anyone on your network is treated as you. Before exposing it beyond localhost, open Settings → Security and set the login mode to simple (username + password + a mandatory authenticator code). And do not port-forward 8787 to the public internet — use Tailscale or a Cloudflare Tunnel (both below) for that.

Any of your devices, anywhere — Tailscale

Want Fanad on your phone when you're out, without ever putting it on the public internet? Tailscale is a private mesh network (a WireGuard VPN with the hard parts done for you): install it on the Fanad PC and on your other devices, sign them into the same account, and they form their own private network — no public URL, no open ports, nothing exposed to the internet.

  1. Install Tailscale from tailscale.com on the Fanad PC and on each device you want to reach it from, and sign them all into the same account.
  2. On the Fanad PC, note its Tailscale address — a 100.x.y.z IP or its MagicDNS name (e.g. fanad-pc).
  3. From any of your other signed-in devices, open http://fanad-pc:8787 (or http://100.x.y.z:8787). It works from anywhere, over the private network.
Private by design

Only your own signed-in devices can reach the box, so this is about as safe as your home network — and the simplest way to get Fanad on your phone from anywhere. A login is still worth turning on, but there's no public surface to attack. Prefer this over a Cloudflare Tunnel unless you need a public URL you can reach from devices that don't run Tailscale.

A custom domain — Cloudflare Tunnel

To reach Fanad from the wider internet with a real HTTPS address like https://fanad.yourdomain.com — and without opening any ports on your router — put it behind a Cloudflare Tunnel. You'll need a domain on a Cloudflare account.

  1. Install cloudflared (the tunnel client) from Cloudflare's downloads.
  2. Authorize it against your Cloudflare account: cloudflared tunnel login.
  3. Create a named tunnel: cloudflared tunnel create fanad.
  4. Point your domain at it: cloudflared tunnel route dns fanad fanad.yourdomain.com.
  5. Create a small config file telling the tunnel to forward to Fanad: 
    tunnel: fanad
credentials-file: C:\Users\you\.cloudflared\<tunnel-id>.json

ingress:
  - hostname: fanad.yourdomain.com
    service: http://localhost:8787
  - service: http_status:404
  6. Run it: cloudflared tunnel run fanad. Your domain now reaches Fanad over HTTPS.

Then lock down the Fanad side — the tunnel puts the otherwise-open web app on the public internet, so don't stop at the tunnel:

  • Set the Site URL. In Settings → Security, set the Site URL to https://fanad.yourdomain.com so the one-time /web sign-in links point at your domain.
  • Best for a single user — lock it to your own IP. In the Cloudflare dashboard, add a Cloudflare Access application (Zero Trust → Access → Applications) in front of fanad.yourdomain.com with a policy that allows only your IP address(es). Then turn on Fanad's own Web IP allow-list (Settings → Security) restricted to the same addresses, and set TRUST_PROXY=1 so Fanad sees your real IP through the tunnel. With the box reachable only from your addresses, running single-user (login mode none) is fine.
  • Otherwise — require a login. If you can't pin your IPs (you roam, or your address changes), turn on web login (mode simple + a mandatory authenticator code) before exposing the UI. Never put the open, no-login web app on a public URL — anyone who reaches it is treated as you.
Pick a tunnel you trust

A tunnel that terminates TLS can see the traffic passing through it, so choose your provider deliberately. Telegram and Slack need none of this — they connect outbound and work behind any NAT.

7 · Off to the races

That's it — Fanad is yours. The whole tool fits in three rules: a statement becomes a task, a question runs a command, and answering Fanad's own question counts as that answer. A leading slash is always optional. Here are the first moves worth knowing:

SayWhat happens
(just type a thought)It's filed as a task on your list.
listSee and clear your list.
whatdoFanad suggests one thing to do now, grounded in your own tasks.
mood 🙂Tell it how you feel; it sizes suggestions to match.
x call the bankFile a task due by the end of today.
howtoA guided tour of the everyday moves.
manualAsk the manual a question in plain words.

When you want more, the full manual covers every command and the opt-in modules (notes, lists, diet, journal, timers, and more); the printable cheat sheet is a one-page reference; and the how-tos show real ways people use it. Get it out of your head.