Installation and Setup

Getting started with pinakea takes just a few minutes. By the end of setup, you’ll have a working demo library to explore and a clear path to connect your own documents, web clippings, emails, and notes.

---

System Requirements

• macOS 15 (Sequoia) or later on Apple Silicon
• Internet connection (required for Online mode and all remote generation)
• OpenRouter API key (recommended; required for chat and remote generation, but onboarding can complete without it)
• Mixed mode (optional): requires ~6 GB disk space for local AI models

---

Download and Install

1. Download pinakea from the official website
   • The download page is split into three sections: App Download, Chrome Extension Download, and Obsidian Extension Download.
2. Open the downloaded .dmg file
3. Drag pinakea to your Applications folder
4. Launch pinakea from Applications

On first launch, macOS may ask you to confirm you want to open the app. Click Open to proceed.

pinakea automatically prepares your browser. Install the extension manually from instructions until it becomes available in the Chrome Web Store.

---

First-Run Setup

When you first launch pinakea, a short onboarding flow sets up your first libraries, shows you around the interface, and lets you configure your AI preferences.

Update checks are held until onboarding is finished. After setup, pinakea checks for app updates regularly in the background; you can also run pinakea → Check for Updates… at any time.

Step 1: Welcome

The first page introduces pinakea and explains that onboarding will prepare a ready-to-explore demo before applying your settings.

Step 2: Demo Setup

pinakea ensures two Sets exist:

• Main: empty starter Set for your own sources
• Demo: bundled, pre-processed demo Set (English)

The bundled Demo includes Obsidian-style notes and folder-style documents, and seeds a Browser Clips demo source when Browser Clips storage is available on your Mac. This lets you explore timeline/day/daypart summaries immediately, even before adding your own sources or configuring an API key. Demo is fixed to Online mode, because its bundled sample content is already pre-processed. To test Mixed mode, use or create another Set.

Step 3: Guided Excerpt

pinakea plays a short auto-advancing walkthrough excerpt behind the onboarding modal:

• 6 core UI points
• 3 seconds per step
• blocking guidance (you don’t need to click through the app yet)
• during excerpt playback, the background dimming is temporarily lifted and popovers are shown in higher-contrast styling for readability

This is an excerpt. The final page offers Start FULL tour now.

Step 4: Settings (Mode, Language, Key, Analytics)

pinakea offers two operational modes:

Online Mode (Recommended)

• All AI processing happens via cloud services (OpenRouter)
• Uses state-of-the-art cloud models with billions of parameters
• Delivers the highest quality embeddings, summaries, titles, and tags
• Can process multiple items in parallel for faster initial indexing
• Requires an internet connection and an OpenRouter API key

Mixed Mode (Apple Silicon)

• Runs embeddings, summaries, titles, and tags locally on your Mac
• Chat and long summaries still use cloud services (OpenRouter)
• Processes items sequentially
• Best for smaller Sets when avoiding OpenRouter cost for automatic item processing matters more than speed and output quality
• Can take hours or days on larger Sets and keep your Mac busy

New Sets default to Online Mode. If you expect a Set to contain around 1,000 items or more, choose Online Mode. See Use Online Mode.

You can set an OpenRouter API key now or continue without one.

If you add a key:

1. Visit openrouter.ai/keys
2. Create an account or sign in
3. Generate a new API key
4. Copy and paste the key into pinakea

The key is stored securely in your macOS Keychain and can be tested during onboarding. If you upgraded from an older build, pinakea migrates an existing legacy key automatically on first launch.

Choose your output language in the same settings page.

Note for Demo:

• Demo content is fixed to English.
• Demo language changes are disabled while Demo is active.
• Demo mode is fixed to Online. Use or create another Set to test Mixed mode.

Step 5: Accept Model Licenses (when required)

pinakea can download local AI models to enable Mixed mode (and seamless switching on supported Macs):

• mxbai-embed-large-v1 (~670 MB) — Local embedding model
• Qwen 2.5 7B Instruct (~5 GB) — Local language model for summaries, titles, and tags

Both models are licensed under Apache 2.0. Review and accept the licenses to proceed.

The download typically takes a few minutes depending on your internet connection. You can pause and resume if needed.

Step 6: Completion

The final page confirms onboarding completion and offers:

• Start FULL tour now
• Finish onboarding

Start FULL tour now launches the complete walkthrough immediately. Finish onboarding closes setup without launching the full walkthrough.

After finishing, pinakea keeps you in your empty Main set. To explore sample content, use the set selector in the top-left and switch to Demo.

---

After Setup: Add Your Sources

With setup complete, connect your content sources:

1. Open Settings (Cmd+,) → Sources

2. Click Add Source and choose a type:

   • Files and folders — Documents, PDFs, images, HTML files (Folder source)
   • Browser Clips — Web pages saved via the browser extension
   • Apple Mail — Your email archive
   • Obsidian Vault — Your markdown notes
   • Feedbin — Starred RSS articles

3. Grant pinakea access to the selected folder or account

4. pinakea begins indexing automatically

The status bar at the bottom shows processing progress as items flow through the AI pipeline.

---

Settings overview

Everything you configured during onboarding can be changed later in Settings (Cmd+,). Here’s what you’ll find:

AI — Global controls let you update and test your OpenRouter API key, manage local models, and tune semantic matching. Set-Specific controls let you switch between Online and Mixed mode, choose your chat model, set output language, and adjust Background processing for the current Set. Remember that AI mode, model selection, language, and Background processing are per-Set, so each library can use different settings.

Sources — Add or remove content sources (folders, Browser Clips, Mail, Obsidian, Feedbin) and manage your Sets (libraries). This is also where you create, rename, and delete Sets.

Server — Configure browser access for phones, tablets, Raycast remote mode, and the bundled local MCP bridge for clients like Claude Desktop, Codex, Cursor, and VS Code.

Maintenance — Create manual backups, restore previous states, and export or import Browser Clips. Useful before making major changes or moving to a new Mac.

About — Shows your app version and links to the homepage, release notes, documentation, and credits.

---

Switching AI Modes

You can switch between Online and Mixed mode at any time in Settings → AI for normal Sets.

Because the embedding models are different between modes, switching modes triggers a re-embedding for the current Set (pinakea will confirm).

What happens when you switch:

• Mixed -> Online: pinakea stops the local AI helper, clears local embeddings, AI-generated summaries, AI-generated titles, and LLM tags for the current Set, then Online Mode regenerates them through OpenRouter credit. Your own tags and starred items are preserved.
• Online -> Mixed: pinakea validates the local model files first. If anything is missing or needs repair, it opens the model installer before switching. Online embeddings generated with OpenRouter credit are replaced and cannot be reused for Mixed Mode. Existing summaries, titles, and tags are kept.

For populated Sets at or above 1,000 items, pinakea recommends staying in Online Mode. See Use Online Mode.

---

Troubleshooting

”OpenRouter API key required”

The status bar shows this when no valid API key is configured. Go to Settings → AI → Global and enter your key.

”Could not save OpenRouter API key”

If pinakea shows a warning that it could not save your API key, macOS Keychain rejected the write.

1. Re-enter the key and try saving again.
2. If the warning persists, restart pinakea and retry from Settings → AI.
3. If needed, check macOS security/keychain prompts and allow pinakea access.

Models not downloading

If the model download stalls:

1. Check your internet connection
2. Try pausing and resuming the download
3. Use Settings → AI → Local Models → Repair to retry

Processing seems slow

• Online mode: Check your internet connection; the status bar shows OpenRouter health
• Mixed mode: Processing is sequential to respect your Mac’s resources; this is normal
• Large initial imports take time — let pinakea work through the queue

Need to start fresh?

Use Settings → Maintenance → Backup & Restore to create a backup before making major changes. You can restore any backup later if needed.

---

Related / Next

• Next: General Usage
• Server access: Browser Access Introduction, Local MCP Bridge
• Understand Sets: Sets (Libraries)
• Add sources: Folders, Browsers, Obsidian