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:

Local model

Ollama, LM Studio, or any other OpenAI-compatible local service. Data stays entirely on your machine.

Linkly Official

Forwarded to a third-party model provider via api.linkly.ai. Requests pass through Linkly’s servers.

Third-party direct

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:

1. Filename quick index (seconds)

   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.
2. Full-text extraction and BM25 index (minutes to hours)

   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.
3. Vector embedding (minutes to hours)

   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, 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
Not found even by filename	The file never entered the index at all	The section after that

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.

Index Settings

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.

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.

Index Settings

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.

Offline Installation Guide

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:

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.

Permission denied

The AppImage is not executable. Run:

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.

FUSE, libfuse.so.2, or AppImage mount errors

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:

./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 for background.

GLIBC_x.y, GLIBCXX_x.y, or CXXABI_x.y not found

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.

Exec format error, or uname -m is not x86_64

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.

The process starts, but no window appears or it exits immediately

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:

./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:

cat /etc/os-release
uname -a
echo "session=$XDG_SESSION_TYPE desktop=$XDG_CURRENT_DESKTOP"

The app runs, but its built-in update fails

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:

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:

Settings → General: language, launch at login, shortcut

• 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. 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

Settings → Appearance: theme, font size, Dock icon

• 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

Settings → About: version, updates, data directory

• 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)
• From here you can also jump to the changelog, privacy policy, terms of service, and the CLI and Skills documentation

Settings → Shortcuts: every shortcut in one place

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 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:

1. Open the About page

   In Linkly AI, go to Settings → About.
2. Open the data directory

   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.
3. Grab app.log from the logs subfolder

   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:

macOS

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.

Windows

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.

Linux

In a terminal:

xdg-open ~/.local/share/ai.linkly.desktop/logs

Or copy app.log directly:

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.

macOS

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.

Windows

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.

Linux

In a terminal:

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.

Where to send it

Open a GitHub issue, or reach us through any channel on the community page.