Getting started

Anthracite ships as a signed and notarized macOS desktop app (Apple Silicon). This guide installs it and creates your first vault.

Platform note. The release build is macOS (arm64) only. It is Developer ID signed and notarized, so it should open normally from Applications without Gatekeeper workarounds. Auto-update and Windows/Linux builds are later steps — see docs/PACKAGING.md.

1. Install

You'll have either a .dmg or an Anthracite.app:

• .dmg — double-click it, then drag Anthracite into Applications.
• .app — move it into /Applications yourself.

2. First launch

Open Anthracite from Applications. The signed release should not require a one-time Gatekeeper override.

If macOS still blocks the app (e.g. you built an unsigned dev/smoke build locally), see Troubleshooting — Gatekeeper.

3. What happens on first run

The desktop app is a thin shell around a local backend. On first launch it:

1. Extracts its bundled backend into the app's support folder (~/Library/Application Support/Anthracite/) — a one-time step, so the first launch is a little slower than later ones.
2. Starts the local backend (core-service + folder watcher) on a private loopback port and waits until it's healthy.
3. Shows the window only once the backend is up — so you won't see a dead UI.

Everything runs on your machine over 127.0.0.1. No account, no upload.

Why the Touch ID prompt?

On launch, Anthracite asks for Touch ID (with your Mac password as the usual fallback). Two reasons:

• Your vault is your unfiltered thinking. Journals, half-formed ideas, private notes — the kind of content you wouldn't leave open on a shared or borrowed Mac. The prompt keeps casual eyes out of your second brain.
• It guards your connected accounts. Tokens for reMarkable, Notion, Readwise, and your API keys are stored encrypted in the macOS keychain; the check confirms it's actually you at the keyboard.

Your fingerprint never reaches Anthracite — the check happens entirely inside macOS (Secure Enclave), and the app only learns "yes" or "no". In the current alpha the prompt is deliberately gentle: cancelling it won't lock you out, and your tokens stay encrypted at rest either way. Expect it to become a proper lock as the app matures.

4. Create or open a vault

A vault is just a folder on disk that holds everything Anthracite produces (see Vault layout). You can have as many as you like — e.g. separate Work and Personal brains.

On first run, the onboarding wizard walks you through it:

1. Welcome — a quick intro.
2. Vault — pick a folder to create/initialize as your vault (or point at an existing one).
3. Model — set up an LLM and test it: install a free local model in one click (see Settings & local models) or bring your own API key. The wizard won't continue until a model responds — nothing downstream works without one.
4. Source — add and sync your first source (a file, or connect reMarkable / Apple Notes / Notion / …).
5. Profile — Anthracite reads a sample of that source and profiles how you take notes.
6. Policy — review the ANTHRACITE.md it proposes from that profile; edit freely, this is your vault's policy file and you can change it anytime.
7. Done.

You can re-run the wizard later from Settings → Vault → Re-profile vault.

To switch or add vaults later, go to Settings → Vault:

• Create new vault — pick a folder (or type a path); Anthracite scaffolds the vault template and registers it. No terminal required.
• Add existing vault — register a folder that was already initialized elsewhere.

Choosing a different active vault prompts a guided app restart so Anthracite reloads against the new vault folder.

5. Add your first source

See Capturing content for every path (folder drop, Obsidian, reMarkable, browser clipper, etc.). The fastest way to try it:

1. Drop a .md or .txt file into your vault's raw/inbox/ folder, or
2. Use Import Source in the left panel (paste text or upload a file).

Then select the source and Process it (or turn on Process automatically in Settings).

6. Explore

Policy lives in ANTHRACITE.md at the vault root; operational knobs in .anthracite/config.json. See Core concepts.

Next steps

• Capturing content
• Working with your knowledge
• Editing ANTHRACITE.md
• Troubleshooting