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 AI processing and remote generation)
• OpenRouter API key (recommended; required for AI processing and chat, but onboarding can complete without it)

---

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. The bundled sample content is already pre-processed.

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, Language, Key, Analytics)

pinakea processes embeddings, automatic item summaries, titles, tags, and chat through cloud AI providers via OpenRouter. This provides high-quality results and parallel processing for faster initial indexing. It requires an internet connection and an OpenRouter API key.

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.

Step 5: Add Sources

The Add Sources page lets you connect content now or continue and do it later from Settings → Sources. Folder, Obsidian, Mail, or Feedbin sources start filling your current Set. Browser Clips are available in every Set for web pages you save from the browser.

• Folder / Obsidian / Mail / Feedbin — connect the places pinakea should index.
• Safari Extension — open Safari Extensions and enable the bundled pinakea Clipper.
• Chrome Connector — install the connector for detected Chrome-family browsers, then load the pinakea extension in each browser where you want clipping.

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, review cost, and tune semantic matching. Set-Specific controls let you choose Background and On-demand models plus language for the current Set. Online processing runs at full capacity in the background.

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.

---

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.

Processing seems slow

• Check your internet connection; the status bar shows OpenRouter health
• 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