> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Frequently Asked Questions
> Answers to common questions about Linkly AI.
This page answers some of the questions Linkly AI users ask most often.
## How does Linkly AI protect user data privacy?
Linkly AI is built on a **local-first** architecture. Your documents, full-text index, vector index, and the embedding model itself all run on your device — nothing is uploaded to any server by default.
### What stays on your device
* **Document originals**: stay in their original folders. Linkly AI only reads them — it does not copy or relocate them.
* **Full-text index (BM25)**: built locally with Tantivy.
* **Vector index**: stored in a local database.
* **Embedding model**: a local embedding model runs entirely on your device. Apple Silicon Macs automatically use Metal GPU acceleration.
* **App logs**: written to local files only — never auto-uploaded.
### Where chat data goes
When the chatbot calls a large language model, where the request goes depends on the provider you choose:
Ollama, LM Studio, or any other OpenAI-compatible local service. Data stays entirely on your machine.
Forwarded to a third-party model provider via `api.linkly.ai`. Requests pass through Linkly's servers.
Connects directly to OpenAI, Anthropic, etc. Requests do not pass through Linkly's servers.
You can add, switch, or disable any provider in **Settings → AI Models**.
### User Experience Improvement Program (telemetry)
To help us understand which features are used and how the app is running, Linkly AI sends an **anonymous** usage report by default:
| What is reported | What is NOT reported |
| --------------------------------------------- | ----------------------------------- |
| Feature usage counters (aggregated by action) | Document content, file names, paths |
| App version, OS, architecture | Chat content, search queries |
| A locally generated random device ID | API keys, custom URLs |
You can turn it off any time in **Settings → Data Privacy → User Experience Improvement Program**. Once disabled, any in-memory events that have not yet been sent are discarded as well.
The "Data Privacy" panel in Settings shows a visual breakdown of where each feature's data flows (**Local / Official cloud / Third-party**), so you can see at a glance what does and does not leave your device.
### Privacy commitments
* No third-party analytics SDKs (Google Analytics, etc.).
* We do not read your browser history or clipboard.
* No mandatory account login — core features work offline.
* App logs stay on your machine. They are sent to us only if you explicitly share them.
## How long does Linkly AI take to finish indexing?
Indexing time depends on the **number of files, file types, machine performance**, and **indexing mode**. Linkly AI indexes in three stages:
As soon as files are discovered, their paths and names are written to the full-text index, so you can search by filename even while content indexing is still running.
Document contents (txt, md, html, docx, doc, pptx, xlsx, csv, epub, rtf, pdf, images, plus audio and video once transcription is enabled) are parsed; outlines and metadata are written to Tantivy. Multiple workers can run in parallel.
The local embedding model generates a vector for each document chunk and writes it to the vector index.
### What affects speed
* **File count**: roughly linear with total time.
* **File format**: plain text is fastest; PDFs require page parsing.
* **Machine performance**: Apple Silicon Macs use Metal GPU acceleration for embeddings, which is significantly faster than CPU inference. On Windows / Linux, embedding currently runs on CPU.
* **Indexing mode**: pick `Performance / Balanced / Auto` in **Settings → Indexing**. Performance mode uses higher concurrency and more CPU; Auto upgrades to Performance when the system is idle.
### Rough expectations
These are order-of-magnitude estimates only — actual times vary considerably with hardware and file mix:
| Scenario | Approximate time |
| ------------------------------------------------------------ | ------------------------------ |
| Thousands of plain-text files (txt / md), M-series Mac | A few minutes |
| Tens of thousands of mixed formats (some PDFs), M-series Mac | Tens of minutes to a few hours |
| Many images requiring OCR | Significantly longer |
| Same workload on Windows / Linux pure CPU | Slower than Mac |
You can watch indexing progress live (indexed / pending) at the top of the launcher. Indexing runs in the background and does not block search — once filename indexing is done, search is immediately available.
If you are just trying Linkly AI out, start with a **small knowledge base** (hundreds to thousands of files), then add larger directories once you are familiar with it.
## Why can't I find a particular file?
Start with one triage step — **search for it by filename**. The three possible outcomes point to three completely different problems:
| What searching the filename does | What it means | Where to go next |
| ------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Found, **with a grey Not indexed · … badge** | The file made it into the index, but its content was skipped | [Four reasons](#four-reasons), below |
| Found, **no badge**, but content still isn't searchable | The content hasn't been extracted yet, or the relevant switch is off | [Next section](#found-by-filename-no-badge-but-the-content-still-isnt-searchable) |
| **Not found even by filename** | The file never entered the index at all | [The section after that](#not-found-even-by-filename) |
This step matters: the three cases are handled completely differently, and skipping triage is a good way to spend a long time digging in the wrong direction.
Skipped files are **not** listed anywhere in Settings. **The badge in search results is the only way to discover them** — which is why you have to run the triage step above yourself.
### Four reasons
| Badge | What actually happened |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Not indexed · cloud placeholder** | The file exists in your cloud drive, but **hasn't actually been downloaded to this machine** — all that's on disk is a placeholder |
| **Not indexed · signature mismatch** | The file's real content doesn't match its extension (say, a file named `.pdf` whose content isn't a PDF at all) |
| **Not indexed · no audio track** | This video has no audio track, so there's nothing to transcribe |
| **Not indexed · transcription failed** | Audio or video transcription couldn't complete (undecodable, or an unsupported audio format) |
Hovering the badge gives you the same explanation. These files stay in your search results; they just have no content to search.
### What cloud placeholders are about
iCloud Drive, OneDrive, Dropbox, Synology Drive and similar services all have a **files on-demand** feature (also called "online-only" or "smart sync"): the file is visible in Finder or File Explorer, but its content still lives in the cloud and is only downloaded when you double-click to open it.
Linkly AI **deliberately does not open these files** — opening one triggers a download, which would mean a single indexing pass could pull hundreds of gigabytes of your cloud drive onto your machine, filling the disk and saturating your bandwidth. So it judges by attributes only: recognise a placeholder, skip the body, keep the filename indexed.
**What to do**: in your cloud client, mark the directories you actually need to search as "always keep on this device" (each vendor names it differently — OneDrive calls it "Always keep on this device", Dropbox "Make available offline", iCloud is a right-click "Download Now"). Once the files land locally, Linkly AI notices they've become available on the next scan and **indexes the content automatically** — you don't need to rebuild the index or re-add the folder.
Scans are triggered automatically on app start, on configuration changes (adding or removing folders, for example), and when a burst of file changes is detected. If you want one right now, restarting the app is the easiest way.
### What to do about a signature mismatch
This means the file header's signature bytes don't match the extension. It's common with stub or shortcut files produced by certain sync tools, half-downloaded files from an interrupted transfer, or files whose extension was renamed by hand.
Open it with the corresponding application to check — if it doesn't open at all, Linkly AI was right to skip it; if the extension is simply wrong, correcting the extension is enough.
Linkly AI's trade-off here is **better to miss than to falsely reject**: if reading the file header hits a transient IO error or permission hiccup, it is treated as "content available". A single momentary failure will never permanently mark a real file as a stub.
## Found by filename, no badge, but the content still isn't searchable
No badge means the file itself is fine — it's the **content extraction step** that hasn't happened, or can't. In order of likelihood:
1. **The relevant extraction switch is off.** Images and scanned PDFs depend on **Image Text Recognition (OCR)**; audio and video depend on **Audio transcription** and **Video transcription** — and **those last two are off by default**. Check under **Settings → Index**.
2. **Its turn hasn't come up yet.** OCR and media transcription are the heaviest tasks, so a slow queue is normal. The status detail on the settings page shows what they're currently working on.
3. **This particular file failed to parse.** A corrupted file or an encrypted PDF, for instance. That case produces no badge — the file is simply skipped and not retried.
4. **A legacy `.doc` exported on macOS cannot be parsed yet.** Files produced by `textutil` or by the "Word 97" export in Pages use an internal layout that differs from Microsoft Word's, so they are skipped for now. Re-save them as `.docx` in Word, or convert them to another supported format.
What every switch does, its default, and the meaning of each row in the status detail — all on this page.
## Not found even by filename
This means the file **never entered the index at all**. There are three common causes:
**1. The folder isn't being watched.** Check under **Settings → Folders** that its parent directory is in the list. The first-run onboarding flow only indexes the bundled samples; your own directories have to be added by you.
**2. The format isn't on the supported list.** Linkly AI uses an allowlist: only PDF, DOCX, DOC, PPTX, XLSX, CSV, EPUB, RTF, Markdown, TXT, HTML, images, audio, and video extensions are picked up. **htm and avi are currently not among them** — a file outside the allowlist doesn't even get its filename registered. The full list is in the [Tools Introduction](/docs/en/tools-intro).
**3. It's inside an ignored directory.** The following directories, and everything below them, are skipped wholesale:
* **Hidden directories starting with a dot** (`.git`, `.cache`, `.dropbox.cache` and so on)
* **`node_modules` and `__pycache__`** and similar build / dependency caches
* **NAS sync metadata directories**: `#recycle`, `#SynoRecycle`, `@eaDir` (Synology), `@Recycle` (QNAP)
* **System directories**: `$RECYCLE.BIN`, `System Volume Information`
Inside a Git repository, files excluded by `.gitignore` are likewise not indexed. If your notes happen to sit in a repo's ignored directory, move them out, or add that directory on its own under **Settings → Folders**.
## Why can't I search what was said inside my audio and video files?
Because **audio and video transcription is off by default**. While it's off, media files are still registered in the index (so filename search finds them), but what was said inside them is never transcribed.
Go to **Settings → Index** and turn on **Audio transcription** and **Video transcription**. The app downloads the speech recognition model and then works through all your existing media files automatically — no rescan and no index rebuild required.
This page explains what every switch under **Settings → Index** does, its default, and the full troubleshooting path when indexing goes wrong.
## Can I use the AI features on a machine without internet access (offline / intranet)?
Yes. OCR, speech transcription, and semantic search all run locally (cloud features like the AI chat and Skills installation are the exception) — the only catch is that the model files they depend on (about 870 MB) are normally downloaded on first run. On a machine with no internet access, download the installer and the **official offline model pack** on a connected machine, carry them over, and install step by step.
What to download first, which files to copy over, and how to install — the full flow on one page.
## What should I do if the Linux AppImage will not start?
Linux distributions vary widely in their base runtime libraries, desktop components, and drivers. An AppImage carries most application dependencies, but it does not replace the operating system's glibc, C++ runtime, FUSE, or graphics drivers, so it cannot guarantee that it will run on every Linux distribution.
The current Linkly AI Linux package is an **x86\_64 AppImage** and requires **glibc 2.35 or newer**. Start by running these commands from the directory containing the AppImage:
```bash theme={null}
uname -m
ldd --version | head -n 1
chmod +x LinklyAI-*.AppImage
./LinklyAI-*.AppImage 2>&1 | tee linkly-ai-linux-startup.log
```
`uname -m` should print `x86_64`. The last command launches the app while saving terminal errors so you can match them to the cases below.
The AppImage is not executable. Run:
```bash theme={null}
chmod +x LinklyAI-*.AppImage
./LinklyAI-*.AppImage
```
Do not launch Linkly AI with `sudo`; doing so can leave configuration and data files that your regular user cannot access later.
AppImages normally mount themselves through FUSE. Install the FUSE 2 compatibility library from your distribution's official repository only:
| Distribution | Command |
| ---------------------------------------- | ----------------------------------- |
| Ubuntu 22.04 / Debian 12 and derivatives | `sudo apt install libfuse2` |
| Ubuntu 24.04 or newer | `sudo apt install libfuse2t64` |
| Fedora | `sudo dnf install fuse-libs` |
| Arch Linux | `sudo pacman -S fuse2` |
| openSUSE | `sudo zypper install fuse libfuse2` |
If FUSE is unavailable in your environment, you can temporarily extract and run the AppImage:
```bash theme={null}
./LinklyAI-*.AppImage --appimage-extract-and-run
```
This is slower and bypasses FUSE only; it does **not** fix GLIBC, CPU architecture, or driver incompatibilities. See the [official AppImage FUSE troubleshooting guide](https://docs.appimage.org/user-guide/troubleshooting/fuse.html) for background.
The operating system's base runtime is too old, and the failure happens before Linkly AI actually starts:
* `GLIBC_x.y` comes from glibc; the current minimum is glibc 2.35.
* `GLIBCXX_x.y` and `CXXABI_x.y` come from the system C++ runtime, `libstdc++`.
First install all official updates offered by your distribution and reboot. If the error remains, upgrade to a newer release supported by that distribution. Installing FUSE or downloading the AppImage again will not change this result.
Do not manually replace `/lib/.../libc.so.6`, copy glibc or libstdc++ from another distribution, mix repositories from different distributions, or force a downloaded system runtime through `LD_LIBRARY_PATH`. These workarounds can break the desktop, package manager, or the entire operating system.
The package does not match your CPU architecture. The current Linux AppImage is available for x86\_64 / amd64 only; there is no compatible Linux installer for `aarch64` / `arm64` devices yet. Changing permissions or installing runtime libraries cannot fix an architecture mismatch.
This is commonly related to the combination of Wayland / X11, Mesa or proprietary graphics drivers, desktop portals, and WebKitGTK. Install the official system and graphics-driver updates offered by your distribution, then launch again from a terminal and keep the output:
```bash theme={null}
./LinklyAI-*.AppImage 2>&1 | tee linkly-ai-linux-startup.log
```
Avoid copying unknown WebKit, GTK, or graphics environment variables from the internet into permanent system configuration: the same switch can behave differently across WebKitGTK and driver versions. If the app still will not start, send us the following diagnostics together with `linkly-ai-linux-startup.log`:
```bash theme={null}
cat /etc/os-release
uname -a
echo "session=$XDG_SESSION_TYPE desktop=$XDG_CURRENT_DESKTOP"
```
Updating an AppImage requires replacing the current AppImage file. Keep it in a directory writable by your user, such as `~/Applications`, rather than a read-only mount or a root-owned system directory:
```bash theme={null}
mkdir -p ~/Applications
mv LinklyAI-*.AppImage ~/Applications/
chmod +x ~/Applications/LinklyAI-*.AppImage
```
Documentation can solve missing execute permission or FUSE, but it cannot change the GLIBC or CPU architecture required by the binary. If the app never creates `app.log`, use the terminal output saved in `linkly-ai-linux-startup.log` instead.
## Where do I find the settings I need?
The settings window is split into pages by function. These are the ones people look for most:
* **Language**: the interface display language
* **Launch at Login**: start Linkly AI when you log in to your system
* **Silent Launch**: when started at login, stay in the background instead of opening the main window — **on by default**, so indexing and the MCP server run without getting in your way
* **Search Shortcut**: the global shortcut that toggles the [Launcher](/docs/en/use-launcher). Click once to re-record it, or use **Reset to default**. If it says the combination is already in use or reserved by the system, pick another one
* **Linkly AI Space**: the folder that's indexed by default — you can open it or move it elsewhere; see [Linkly AI Space](/docs/en/linkly-space)
* **Theme**: Light / Dark / System
* **Font Size**: Small / Standard / Large, applied to both the interface and chat content
* **Show Dock Icon** (macOS): turn it off and the app lives only in the menu bar tray, taking up no space in the Dock
* **Check for Updates**: manually check for and download a new version; when it's downloaded, click **Restart to Update**
* **Join Beta Program**: get beta updates and early access to new features, at the cost of possibly running into less thoroughly tested changes
* **Data Directory**: where the index, settings, and logs are stored — click **Open** to go straight there (that's where you [grab the log](#how-do-i-get-linkly-ais-application-runtime-logs))
* From here you can also jump to the changelog, privacy policy, terms of service, and the CLI and Skills documentation
Lists every shortcut in the app. Pressing `⌘ + /` (`Ctrl + /` on Windows/Linux) in the Launcher opens this page directly.
**Pause Indexing** is not in Settings — it lives only in the **system tray menu**, and you need to **right-click** the L icon in the tray to bring that menu up (left-clicking opens the AI chat window). See [Index Settings](/docs/en/indexing) for details.
## How do I get Linkly AI's application runtime logs?
While running, the app automatically writes its full log to a local `app.log` file (capped at 2 MB per file, with rotation). Attaching this file when you report an issue dramatically speeds up debugging. Sensitive data is already redacted.
There are two ways to grab the log:
### Option 1: Open from inside the app (recommended)
This is the simplest path:
In Linkly AI, go to **Settings → About**.
Find the **Data Directory** row and click the **Open** button on the right. Your file manager will open at the folder that holds the app's data.
Inside that folder, open the `logs/` subdirectory and send us `app.log`.
### Option 2: Open the data directory manually
If the app has crashed or won't launch, open the folder directly from disk:
1. Open Finder.
2. From the menu bar, choose **Go → Go to Folder…** (or press ⌘ + ⇧ + G).
3. Paste this path and press Return:
```
~/Library/Application Support/ai.linkly.desktop/logs
```
4. Find `app.log` in that folder and send it to us.
1. Press Win + R to open the "Run" dialog.
2. Paste this path and press Enter:
```
%APPDATA%\ai.linkly.desktop\logs
```
3. Find `app.log` in that folder and send it to us.
In a terminal:
```bash theme={null}
xdg-open ~/.local/share/ai.linkly.desktop/logs
```
Or copy `app.log` directly:
```bash theme={null}
cp ~/.local/share/ai.linkly.desktop/logs/app.log ~/Desktop/
```
### What if the app crashes during startup?
If the app crashes immediately on launch, `app.log` may not have been written yet. In that case we save the crash information to a separate **startup crash log** `linkly-ai-startup-panic.log`. Find it at the path below.
1. Open Finder.
2. From the top menu choose **Go → Go to Folder…** (or press ⌘ + ⇧ + G).
3. Paste the path below and press Enter:
```
~/Library/Application Support
```
4. Find `linkly-ai-startup-panic.log` in that folder and send it to us.
1. Press Win + R to open the "Run" dialog.
2. Paste the path below and press Enter:
```
%LOCALAPPDATA%
```
3. Find `linkly-ai-startup-panic.log` in that folder and send it to us.
Note that this path uses `%LOCALAPPDATA%` (local data), not the `%APPDATA%` (roaming data) used by `app.log`.
In a terminal:
```bash theme={null}
cp ~/.local/share/linkly-ai-startup-panic.log ~/Desktop/
```
This log is only created when a crash happens during startup, and each crash overwrites the previous one. If this file does not exist either, take a screenshot of the crash dialog or window and send it along with your OS version.
Open a GitHub issue, or reach us through any channel on the community page.