> ## 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. # Setup Guide for Agents > Hand this page to your AI agent and let it walk you through installing, integrating, and verifying Linkly AI This page is written primarily for **AI agents**, not for people. If you use an AI assistant with shell access — Claude Code, Codex, Cursor, and the like — copy the line below and send it to your assistant. It will read this page and walk you through the setup: ``` Please read https://linkly.ai/docs/en/agent-setup.md and guide me through installing and integrating Linkly AI ``` You are welcome to read on yourself — this is also a complete setup guide. It is just written more bluntly than most, with a heavy emphasis on how to tell whether each step actually worked. If your AI assistant cannot access the web, use **Copy page** in the top-right corner to grab this page as raw Markdown and paste it in directly. *** ## To the AI agent Everything below is addressed to you. Read all of it before you start. ### Your task Guide the user through installing and integrating Linkly AI. You are done when: 1. The Linkly AI desktop app is installed, initialized, and indexing — **the bundled samples alone are enough**; the user's own documents are a bonus; and 2. You — or another AI tool the user owns — can genuinely call Linkly AI's retrieval tools and find a real document. ### Your boundaries and rules Some things you can do yourself; others must be handed to the user. **Do not overstep, and do not assume an outcome on the user's behalf:** * **You can do yourself**: run probe commands, install the CLI, configure MCP, install Skills, run verification commands, interpret errors, report back. For anything that installs software, **show the command and get consent first**. * **The user must do**: download and run the installer, complete the setup wizard, add document folders in the app, grant system permissions. These are GUI actions — you cannot do them. And a few hard rules: * **Probe before you act.** The user may be half set up already, or reinstalling — do not blindly run through every step from the top. * **Verify every step.** Each step states its acceptance check. If the check does not pass, do not move on. * **When the user must act, say everything at once, then stop and wait for a single reply.** Do not split one task into several rounds of back-and-forth confirmation. * **Show install commands and get consent before running them** — especially anything that downloads and executes a script from the network. * **Never overstate progress.** If it is not verified, it is not done. Say exactly where you are stuck and what you tried. * **Do not bypass permission, security, or verification requirements.** When Troubleshooting doesn't cover a problem, run `linkly doctor` first and check the relevant official guide; if you use an approach not listed here, state your reason and re-verify. ### First, check whether you can run commands This guide assumes you have shell access — Claude Code, Codex, Cursor, Gemini CLI, and the like. If you are an **online application without a shell**, such as ChatGPT or Claude.ai on the web, you cannot run the probe commands below and cannot install the CLI — the one thing that still applies is that **the desktop app must be installed** (relay Step 1 to the user in full). How you connect (remote MCP, uploading Skills, and so on) varies a lot per application, so read `https://linkly.ai/docs/llms.txt`, find the integration guide for the application you are running in (for example "Using Linkly AI in ChatGPT"), and follow that page to guide the user — do not generalize from this one. *** ## Step 0: Probe the current state Run this batch first, then use the result to decide where to start. **macOS / Linux (bash / zsh):** ```bash theme={null} echo "--- 1. port file ---" cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE" echo "" echo "--- 2. health ---" PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null) curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE" echo "" echo "--- 3. cli ---" linkly --version 2>/dev/null || echo "NO_CLI" echo "--- 4. status ---" linkly status --json 2>/dev/null || echo "NO_STATUS" echo "--- 5. skills ---" ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS" ``` **Windows (PowerShell):** ```powershell theme={null} Write-Output "--- 1. port file ---" $port = 60606 if (Test-Path "$HOME\.linkly\port") { Get-Content "$HOME\.linkly\port" $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port } else { Write-Output "NO_PORT_FILE" } Write-Output "--- 2. health ---" try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" } Write-Output "--- 3. cli ---" if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" } Write-Output "--- 4. status ---" if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" } Write-Output "--- 5. skills ---" if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" } ``` ### How to read the results `/health` is the single most reliable probe. When the service is running it returns HTTP 200 and a JSON body: ```json theme={null} { "version": "0.8.1", "doc_count": 12009, "mcp_endpoint": "http://127.0.0.1:60606/mcp", "index_status": "watching", "capabilities": ["clips-v1"] } ``` Key points: * **Never hardcode port 60606.** It is only the default; if the port is taken the app increments upward. Always read the real port from `~/.linkly/port`, whose contents are compact JSON: `{"port":60606}`. * **A port file does not mean the service is running.** The file is left behind when the app is force-killed or crashes. Judge health solely by whether `/health` returns 200. * **`mcp_endpoint` being `null` means the MCP toggle is switched off** (`/health` still returns 200). Don't go debugging the port — have the user turn it on under **Settings → MCP**. * **`index_status` values**: `watching` (finished — the CLI shows `Up to date`), `scanning`, `indexing`, `idle`, `error`. * **`doc_count` is the number of indexed documents** — use it to gauge indexing progress, not as hard proof that the user's files landed: it's just a total, and 151 vs 150 is barely distinguishable when only a file or two was added. ### State table **Match top to bottom and follow the first row that hits** (the table routes on link state along a single axis, so the rows are mutually exclusive): | Probe result | Meaning | Start at | | ---------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | No port file, `/health` unreachable | Not installed, or never launched | Step 1 | | Port file exists, `/health` unreachable | Installed but not running | Ask the user to launch it, then re-probe | | `/health` 200, but `index_status` is `error` | Indexing failed | Run `linkly doctor` first (no CLI → have the user open **Settings → About → Logs**); don't continue until it recovers | | `/health` 200, but `linkly status` doesn't work | App ready, CLI missing (or can't connect) | Step 2 | | `/health` 200 and `linkly status` fine, but Skills not installed | Chain ready, Skills missing | Step 3 | | All of the above ready, and Skills installed | Essentially set up | Step 4 verification | Note: whichever step you enter at, if `doc_count` is only at sample level (\~150), suggest — in your final report — that the user add their own folders under **Settings → Folders**. It is not a blocker; keep going. *** ## Step 1: Install and initialize This step is entirely manual — you cannot do any of it. **Give the user the full sequence below in one message, then stop and wait for a single "done" reply.** Do not walk through it item by item across multiple rounds. Here is what to relay to the user (rephrase in your own voice if you like, but cover all five parts): ### 1. Download and install Go to **[https://linkly.ai/#download](https://linkly.ai/#download)** and grab the build for your operating system. * **macOS**: double-click the `.dmg` to mount it, drag the **LinklyAI** icon into **Applications**, then launch it from Launchpad. * **Windows**: double-click the `.exe` and follow the wizard (installs to the user directory by default), then launch it from the Start menu. * **Linux**: AppImage — `chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage`; or deb — `sudo dpkg -i linkly-ai-*.deb`. ### 2. Complete the first-launch wizard The first launch opens a guided window: **cover → sign-in → preparing → get-started panel** (the step counter in the bottom right only counts the middle two, showing 1/2 and 2/2). * **Cover**: pick the interface language and theme. **You must tick "I have read and agree to the Privacy Policy" to continue.** The same screen has a "Help improve Linkly AI" telemetry toggle, on by default, which you can turn off. * **Sign-in** (1/2): clicking "Sign in / Sign up" opens the browser for OAuth. **This step can be skipped** — the skip entry is a "skip sign-in" link in a line of small text at the bottom. Tell the user: signing in is only for quickly getting the official AI model trial quota and cloud knowledge-base features, which makes trying it out easier; **local indexing, local search, and the MCP service need no network connection at all**. * **Preparing** (2/2): the app unpacks a set of bundled sample documents and indexes them, usually within a few minutes. Wait for the "Get started" button to light up. * **Get-started panel**: six feature cards. Click any card to try the main feature; click the × in the top-right corner to finish the wizard. ### 3. Add your own document folders (optional) When the wizard ends, only the bundled sample documents are indexed — the user's own files are not. Worth suggesting, but not required: the samples are enough to try Linkly AI out, and folders can be added at any time later. Either way works: * Open **Settings → Folders** and add the directories to index (Documents, Downloads, a project directory, and so on); * Or drop files into the `~/LinklyAI` folder — it is watched by default, so anything placed there is indexed automatically. If the system reports insufficient permissions (common on macOS), go to **System Settings → Privacy & Security → Full Disk Access**, add Linkly AI, then restart the app. Suggest the user add their own folders that hold lots of local files — Documents, cloud drives, NAS, and the like — to the index. ### 4. Know that models are downloading in the background (no action needed, but tell the user) After first launch the app downloads roughly **710MB** of model files in the background (about 639MB for semantic search, about 70MB for OCR). Depending on the connection this can take from a few minutes to over an hour. During that window: * **Keyword search works immediately** and is completely unaffected; * **Semantic search waits for the download and indexing to finish.** Until then `search` automatically falls back to keyword-only (full-text) retrieval — relevance drops slightly. That is expected behavior, not a fault. ### 5. Reply once when all of it is done Once all of the above is done, reply to the user once in a grateful tone — you will take over the rest. *** **Acceptance check**: `/health` returns 200 and `doc_count` is above 0. If you just finished the wizard and `doc_count` is still 0 while `index_status` is `scanning`/`indexing`, the samples are still being ingested — **retry every 10 seconds, up to 6 times**; if it's still 0, treat it as the `error` case in Troubleshooting. If the user added their own folders, `doc_count` will be clearly above the sample level; if they did not, that is no reason to hold up the rest. *** ## Step 2: Connect the tool path There are two routes, and they are **not mutually exclusive**. **Install the CLI first**: it works the moment it's installed, so you can call it and close the loop within the current session; MCP needs a session restart before it works, so you can't verify it on the spot. This is only a "can I self-verify in this session" priority — it does not mean the CLI is better than MCP as a product. If the user also wants Linkly AI in another AI tool, you can set up both. **Don't hardcode the port in any command below.** At the start of this step, pull the real port into a variable and reference it from then on: ```bash theme={null} PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port) MCP_URL="http://127.0.0.1:$PORT/mcp" ``` On PowerShell, reuse the `$port` from Step 0: `$mcpUrl = "http://127.0.0.1:$port/mcp"`. ### Option A: Install the CLI (recommended) Show the user the command, explain that it downloads and executes an install script from the network, and **get consent before running it**: macOS / Linux: ```bash theme={null} curl -sSL https://updater.linkly.ai/cli/install.sh | sh ``` Or via Homebrew: ```bash theme={null} brew tap LinklyAI/tap brew install linkly ``` Windows (PowerShell): ```powershell theme={null} irm https://updater.linkly.ai/cli/install.ps1 | iex ``` Any platform (requires a Rust toolchain): ```bash theme={null} cargo install linkly-ai-cli ``` The install script installs the CLI and adds it to your PATH. If `linkly` is not found afterwards, have the user **open a new terminal window** (PATH changes don't apply to already-open windows), or invoke the full path directly: * macOS / Linux: installed at `~/.linkly/bin/linkly`, with PATH added to `.zshrc` / `.bashrc` / `.profile`; * Windows: installed at `%LOCALAPPDATA%\linkly\bin\linkly.exe`, modifying the user-level PATH. **Acceptance check**: `linkly --version` prints a version, and `linkly status --json` returns JSON containing `app_version` and `doc_count`. (In the human-readable `linkly status`, that field is labeled `Docs:` and carries thousands separators; for programmatic checks always use `--json`.) ### Option B: Configure MCP Use this when the CLI is awkward to install in the user's environment, or when they want Linkly AI across several AI tools. Use the `$MCP_URL` from the start of Step 2 (i.e. `http://127.0.0.1:$PORT/mcp`) — **do not hardcode 60606**. Common clients: * **Claude Code**: `claude mcp add --transport http linkly-ai "$MCP_URL"` * **Codex**: `codex mcp add linkly-ai --url "$MCP_URL"` * **Cursor**: Settings → MCP Servers → Add Server; Name `linkly-ai`, Type `StreamableHTTP`, URL is the resolved value of `$MCP_URL`. For other clients, see [Integrate with AI Assistants via MCP](/docs/en/use-mcp). **A newly configured MCP server usually does not become available in the current session** — most clients need to reload the config or start a new session; follow the client's own guide. Tell the user plainly: "the configuration is written, reload/start a new session and try again." **Do not keep probing the current session to see whether the tools have appeared.** **Acceptance check**: the configuration was written successfully. To confirm the server itself is healthy without restarting anything, send a handshake directly (replace `$MCP_URL` with the resolved value): ```bash theme={null} curl -sf --max-time 5 -X POST "$MCP_URL" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}' ``` A response containing `"serverInfo":{"name":"linkly-ai"` means the MCP service is healthy; a **403** means the MCP toggle is off — have the user turn it on under **Settings → MCP**. *** ## Step 3: Install Skills Skills teach you how to use Linkly AI's tools well — search first, then outline, then read the parts that matter — which measurably improves retrieval quality. **Strongly recommended.** Again, show the command and get consent before running it: ```bash theme={null} npx skills add LinklyAI/linkly-ai-skills ``` If `npx` is unavailable, clone manually: ```bash theme={null} # Claude Code (user level) git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai # Codex CLI git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai ``` Some users can't reach GitHub — download our fallback package from the Linkly CDN instead: ``` https://updater.linkly.ai/skills/linkly-skills-latest.zip ``` To install for a specific client only (e.g. `-a claude-code` / `-a codex`) or other methods, see [Using Skills](/docs/en/use-skills). If the target directory already exists, it's already installed — skip it (to update, `cd` in and `git pull`). **Skills also require a session restart to load.** The acceptance check is that the files landed in the right directory — not that the current session can already invoke them. Remind the user to restart afterwards. **Acceptance check**: a `SKILL.md` file exists at any of these paths — `~/.claude/skills/linkly-ai/SKILL.md` (Claude Code user level), `.claude/skills/linkly-ai/SKILL.md` (project level), `~/.agents/skills/linkly-ai/SKILL.md` (Codex). `npx skills add` picks one automatically based on the detected client, so just check these three paths afterwards. *** ## Step 4: End-to-end verification **If you installed the CLI (Option A)**: run one real search to confirm the whole chain works. Check `doc_count` first — at sample level (\~150), search a word from the sample library (e.g. `Holmes`); clearly above sample level means the user added their own folders, so use a word likely to appear in their documents: ```bash theme={null} linkly search "Holmes" --json ``` **Success means**: real document entries came back (when running on the samples only, hitting the sample docs counts as success too). **If you only went the MCP route (Option B)**: you cannot finish this step within the current session — the tools only appear after the client reloads or starts a new session, which is the loading mechanism, not a failure. Close out with "config written, server handshake OK, pending user verification after restart", hand the user the line below, then stop (this is not overstating progress): > After reloading/starting a new session, ask me "search Holmes with linkly-ai" — if it returns document entries, the whole chain works. If a CLI search comes back empty, don't jump to blaming the model — with the model not ready, `search` only degrades to keyword-only and won't return empty. Check in order: is the query reasonable → is `doc_count` 0 (samples still ingesting, see the Step 1 acceptance check) → did the user add folders → is the format supported. Use `linkly status --json` to read `index_status`: `indexing` means it's still building the index or downloading models — just wait; `error` → see Troubleshooting. Note: in the brief gap between the end of scanning and the start of content extraction, `index_status` shows `watching` (i.e. `Up to date`) prematurely. **Do not judge readiness from a single sample** — check again a few seconds later, or watch whether `doc_count` is still climbing. *** ## Troubleshooting | Symptom | Cause and fix | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/health` connection refused | The desktop app is not running. Ask the user to launch it and retry. | | Port file exists but `/health` fails | Stale file from an unclean shutdown. Ask the user to relaunch the app. | | Port unreachable but the app is running | 60606 was taken and the port incremented. Read the real port from `~/.linkly/port`. | | `/health` fine but the handshake returns **403** | The MCP toggle is off. Have the user turn it on under **Settings → MCP**. | | `index_status` is `error` | Indexing failed. Run `linkly doctor` (no CLI → have the user open **Settings → About → Logs**); don't continue until it recovers. | | `linkly` command not found | Have the user open a new terminal; macOS/Linux use `~/.linkly/bin/linkly`, Windows use `%LOCALAPPDATA%\linkly\bin\linkly.exe`. | | PowerShell says the script is blocked | Execution-policy restriction. Have the user run `Set-ExecutionPolicy -Scope Process -Bypass` in the same window (that window only) and retry, or use `cargo install linkly-ai-cli`. | | Empty search | Don't blame the model first (when the model isn't ready it degrades to full-text and won't return empty). Check in order: query, whether `doc_count` is 0, whether the user added folders, whether the format is supported. | | `index_status` stuck at `indexing` | Normal for large collections or an in-flight model download. Watch whether `doc_count` is climbing. | | Permission errors on macOS | **System Settings → Privacy & Security → Full Disk Access**, add Linkly AI, restart the app. | | MCP configured but tools never appear | Needs a config reload or a new session. This is the client's loading behavior, not a config error. | | Need deeper diagnostics | Run `linkly doctor` — it checks the connection chain step by step and suggests fixes. | *** ## Report back when you are done Close with a short summary for the user covering: * which steps you completed, and by which route (CLI or MCP); * whether a session restart is needed for anything to take effect; * the current index status and document count; * how to actually use it — for example appending `use linkly-ai` to any prompt, or pressing `CMD/Ctrl + Shift + L` to open the search launcher. If any step could not be completed, say so plainly: where you got stuck, what you tried, and what the user can do next. ### Finish with four example questions End your report with four questions the user can copy and try immediately. **Tailor them to the user's actual material whenever you can**: Take a moment to see what they indexed — run the `explore` tool (`linkly explore` on the CLI) to get the shape of the collection, and `search` a few themes if you need more detail. Then write four questions they would genuinely ask: grounded in their own documents and concerns, not generic filler like "summarize my documents." A good question makes the user think "that is clearly about my files." If the user has not added their own documents yet (`doc_count` is still at the sample-only level), use these four, which target the bundled sample library: 1. Read A Life in 10 Years and analyze the recurring life patterns across Samuel Pepys's decade of diaries — and the blind spots he himself may never have seen. 2. What really makes Sherlock Holmes win? Read the 12 cases in Detectives Library, distill his case-solving formula, then turn Holmes's method into a checklist for diagnosing complex business problems. 3. What did America's founders truly fear? Read the entire Federalist Papers and give me an answer. Explain how they designed a system that pits ambition against ambition and faction against faction — then translate that logic into governance principles for today's AI companies or internet platforms. 4. After reading firsthand memories from hundreds of formerly enslaved people, what do American history textbooks least dare to spell out? Answer based on the WPA Slave Narratives. *** ## Further reading * [Quick Start](/docs/en/quickstart) — the full installation and onboarding guide, written for people * [Using CLI](/docs/en/use-cli) — every CLI subcommand and parameter * [Using MCP](/docs/en/use-mcp) — the three access modes and per-client configuration * [Using Skills](/docs/en/use-skills) — how Skills install and how they work