Installation and Setup - ONA.UNO Docs

Getting started with ONA.UNO 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
• 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 Apple Silicon and ~6 GB disk space for local AI models

---

Download and Install

1. Download ONA.UNO from the official website
2. Open the downloaded .dmg file
3. Drag ONA.UNO to your Applications folder
4. Launch ONA.UNO from Applications

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

---

First-Run Setup

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

Step 1: Welcome

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

Step 2: Demo Setup

ONA.UNO 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.

Step 3: Guided Excerpt

ONA.UNO 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)

ONA.UNO 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
• Lower ongoing cloud costs; can work offline for core pipeline stages (after model install)
• A solid alternative when privacy or cost is a priority

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 ONA.UNO

The key is stored securely in your macOS Keychain and can be tested during onboarding. If you upgraded from an older build, ONA.UNO 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.

Step 5: Accept Model Licenses (when required)

ONA.UNO 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, ONA.UNO 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 ONA.UNO access to the selected folder or account

4. ONA.UNO 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 — Switch between Online and Mixed mode, choose your chat model, manage local models, and update your OpenRouter API key. Remember that AI mode and model selection 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.

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.

Developer — Advanced options for power users: control parallel processing concurrency in Online mode, and enable detailed logging for troubleshooting.

---

Switching AI Modes

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

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

What happens when you switch:

• Mixed → Online: ONA.UNO clears AI micro summaries, AI titles, and AI tags for the current Set so Online mode regenerates them. (Your own tags and starred items are preserved.)
• Online → Mixed: ONA.UNO keeps existing AI micro summaries/titles/tags, but still re-embeds for the current Set. If local models are missing, ONA.UNO will prompt you to download them first.

---

Troubleshooting

”OpenRouter API key required”

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

”Could not save OpenRouter API key”

If ONA.UNO 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 ONA.UNO and retry from Settings → AI.
3. If needed, check macOS security/keychain prompts and allow ONA.UNO 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 ONA.UNO 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
• Understand Sets: Sets (Libraries)
• Add sources: Folders, Browsers, Obsidian