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 includes the macOS app, Raycast source ZIP, Chrome extension guidance, and Obsidian plugin links. The Obsidian plugin is installed through BRAT using myfineapps/pinakea-obsidian-companion.
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.

The Chrome extension ships inside pinakea. To install or update it later, open Settings -> Sources and click Chrome Connector in Add Sources.

---

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 grouping and automatic 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.

Step 4: Set Up pinakea (Account, 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, automatic item 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, automatic item summaries, titles, and tags locally on your Mac
• Chat, full item summaries, day/daypart summaries, and AI tag consolidation 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.

The settings page also asks you to create or sign in to your pinakea account. Enter your email; if you do not have a pinakea account yet, pinakea registers you and sends a code. There is no separate signup page. The bundled Demo remains available during onboarding, but the real library stays locked until sign-in is complete. If you do not want to sign in yet, choose Quit pinakea to leave setup without completing onboarding.

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.

Conditional: Accept Model Licenses (Mixed mode only)

pinakea downloads local AI models only when a Set actually needs Mixed mode. If you keep the recommended Online mode during onboarding, this download is skipped. If you choose Mixed mode, pinakea asks you to review the model licenses and then downloads:

• 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 cancel before starting, pause and resume after starting, or close a failed download and retry later.

Step 5: Add Sources

The Add Sources page shows buttons for Folder, Obsidian, Mail, Feedbin, Safari Extension, and Chrome Connector. Folder, Obsidian, Mail, or Feedbin sources start filling your current Set. Browser Clips are always available as the Set-scoped browser capture source.

• Safari Extension — opens Safari’s Extensions settings so you can enable the bundled clipper. The setup status reads Enabled, Not enabled yet, or Status unavailable.
• Chrome Connector — installs or refreshes connector setup for detected Chrome-family browsers, then keeps a floating setup panel visible while you load the extension in the browser.

If you have not added a Folder, Obsidian, Mail, or Feedbin source yet, the next button reads Skip for now. Once one of those content sources is connected, it changes to Continue.

Step 6: Completion

The final page offers Start Full Tour and Finish onboarding.

Start Full Tour completes onboarding, closes the setup sheet, and launches the complete walkthrough immediately. Finish onboarding closes setup without launching the full walkthrough.

After finishing, pinakea keeps you in your 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. Use the Add Sources buttons:

   • Files and folders — Documents, PDFs, images, HTML files (Folder source)
   • Obsidian Vault — Your markdown notes
   • Apple Mail — Your email archive
   • Feedbin — Starred RSS articles
   • Safari Extension — Enable the bundled Safari clipper
   • Chrome Connector — Set up or repair Chrome-family Browser Clips

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:

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.

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, set output language, and adjust Background processing for the current Set. Remember that AI mode, language, and Background processing are per-Set, so each library can use different settings.

Web Server — Configure Web Server for phones, tablets, Raycast remote mode, and MCP Connector 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 automatic item summary records, 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. If the download fails, use Retry or close the installer and try again later. Mixed-mode processing waits until the models are repaired.
4. 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
• Web Server access: Web Server Introduction, MCP Connector
• Understand Sets: Sets (Libraries)
• Add sources: Folders, Browsers, Obsidian