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

# Using Cloud Libraries

> Push a local library to the cloud so it stays online around the clock, searchable by any AI assistant without your computer — and shareable with others.

## What Is a Cloud Library

A [library](/docs/en/use-libraries) lives only on your own computer by default — if the app isn't running or the machine is offline, nothing can search it. A **cloud library** is a copy of one local library pushed to Linkly AI's servers: it stays online around the clock, doesn't depend on your computer, can be searched directly by any MCP-capable AI tool, and can be shared with other people.

<CardGroup cols={2}>
  <Card title="Online Without Your Machine" icon="cloud" iconType="duotone">
    Your AI assistant can still search the content with the computer shut down
    and the app closed
  </Card>

  <Card title="Shareable" icon="users" iconType="duotone">
    Publish it openly, or invite specific people by email
  </Card>
</CardGroup>

### How This Differs from Remote Access

The two features have similar names but solve opposite problems, which makes them easy to confuse:

| Feature                                         | Problem it solves                                                              | Depends on your computer       | Shareable | Plan |
| ----------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ | --------- | ---- |
| [Remote Access](/docs/en/use-in-remote) (MCP tunnel) | Lets a cloud AI application **reach back into your machine** to read documents | Yes — must be on and connected | No        | Pro  |
| **Cloud library**                               | Takes selected content **off your machine** and online for more agents to use  | No                             | Yes       | Free |

A quick way to decide: want ChatGPT to read **all** the documents on your computer → use remote access; want one specific set of material to be **online permanently** and usable by others → use a cloud library. The two work fine side by side.

### When to Use It

* **You need it available around the clock**: on your phone, while traveling, or with the computer switched off
* **You're supplying material to a team or client**: turn product docs, specs, or a case library into one shareable library
* **You're publishing a knowledge base**: a curated collection anyone can search with their own AI assistant
* **You use several machines**: push once, search everywhere, without re-indexing on every computer

***

## Create and Push (Owner's View)

A cloud library starts as an empty shell created on the web, which you then fill by pushing local content from the desktop app.

<Steps>
  <Step title="Create a cloud library on the web">
    Sign in at [linkly.ai](https://linkly.ai), go to **Dashboard → My Libraries**, and click **New** (direct link: `https://linkly.ai/libraries/new`).

    The first time you create one, you'll be asked to set a **username** — a cloud library's address looks like `linkly.ai/<username>/<slug>`, so the account needs a unique username.

    Fill in the **New cloud library** form:

    * **Library title**: the display name, in any language you like
    * **Slug**: the segment that appears in the address — 6–60 characters, lowercase letters, numbers, and hyphens only
    * **Description (optional)**: one line on who the library is for and what's in it
    * **Category**: makes the library easier to discover; changeable at any time
    * **Visibility**: see [Sharing with Others](#sharing-with-others) below
  </Step>

  <Step title="Bind it in the desktop app">
    Once it's created you'll see a **Bind in Linkly Desktop** button, which launches the desktop app.

    If nothing launches, use **Copy library URL** on the page and bind manually in the desktop app: open **Settings → Libraries**, select the local library you want to push, click **Already created one? Paste the library URL** in the **Cloud Library** panel, paste it in, and click **Bind**.

    <Note>
      Binding is a one-to-one relationship between a **local library and a cloud library**. The cloud library is a copy of the local one, and the local side is the source of truth.
    </Note>
  </Step>

  <Step title="Push the content">
    After binding, the **Cloud Library** panel shows how many documents are waiting to be pushed. Click **Push** to start uploading — you can pause, resume, and inspect processing details along the way, and clicking again after an interruption resumes from where it stopped.

    When the push finishes, the card reads **Synced to cloud** along with the document count. Whenever you add or change something locally, the card switches to **Local has changes** — push once more and you're up to date.
  </Step>

  <Step title="Turn on auto sync (recommended)">
    Switch on **Auto sync** in the **Cloud Library** panel and the app checks for changes every 5 minutes and pushes them for you, so there's nothing left to click.
  </Step>
</Steps>

### Unbinding

Choose **Unbind this cloud library** from the menu in the library's **Cloud Library** panel and the local side stops pushing. **Content already in the cloud is kept**, and you can re-bind at any time.

To delete the cloud copy entirely, go to the library's settings page on the web → **Danger zone** → delete the library. Deleting also clears the files, invitations, stars, and everyone's links — it cannot be undone.

***

## Linking a Library (User's View)

Before an AI assistant can search a cloud library, you have to **link** it to your account: open the library's web address and click the **Link** button in the top-right corner. The button turns into **Linked** when it succeeds.

<Warning>
  **Even a library you created yourself has to be linked once.** What MCP can
  search is decided by the link relationship, not by ownership — an unlinked
  library is invisible to your AI assistant, even if it's your own.
</Warning>

A link is a relationship between **your account** and **that library**, independent of the owner:

* The owner can see who has linked their library (library settings → **Users**)
* You can click again at any time to unlink, which doesn't affect the library itself
* Each link occupies one **slot**: free accounts get 1, Pro gets 99

***

## Using It with an AI Assistant

Cloud libraries are exposed for retrieval through Linkly AI's cloud MCP gateway, at a fixed endpoint:

```
https://mcp.linkly.ai/mcp
```

When adding it in an AI client, **name the server `linkly-ai-cloud`**. That name keeps it distinct from `linkly-ai`, the local desktop app — the two can be configured at the same time without interfering, whereas sharing one name means they overwrite each other.

### Three Ways to Connect

| The tool you use                                  | How to connect                                               |
| ------------------------------------------------- | ------------------------------------------------------------ |
| Claude Code, Codex, Cursor, Gemini CLI, and so on | HTTP MCP + an API key (sent as a `Bearer` request header)    |
| ChatGPT, Claude.ai, and other online applications | Fill in the URL and authorize over OAuth — no API key needed |
| Linkly AI CLI                                     | Run `linkly auth set-key`, then add the `--remote` flag      |

Claude Code, for example:

```bash theme={null}
claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_YOUR_KEY"
```

API keys are created in the **API Keys** section of the [dashboard](https://linkly.ai/dashboard/integrations) and start with `lkai_`. For the exact configuration format per client, see the [Integration Guide](/docs/en/integration).

<Tip>
  Don't feel like configuring it by hand? Click **Use in AI** on any cloud
  library page and send the line from the dialog to your AI assistant — it will
  read the [setup guide](/docs/en/library-setup) and walk you through the whole
  thing.
</Tip>

### How to Specify a Library

A cloud library's identifier looks like `cloud://<owner>/<slug>` — the same two segments that appear in the web address:

```
Web address    https://linkly.ai/blueeon/linkly-init-example
Identifier     cloud://blueeon/linkly-init-example
```

`list_libraries` lists every library you've linked, along with its exact identifier.

<Warning>
  **Every search has to name the library explicitly.** Leave the library
  parameter out and the request is routed to your own machine by default
  (through the remote tunnel), and the tunnel is a Pro feature — free accounts
  get an error straight away. Cloud libraries are **never** pulled in
  implicitly: name the one you want, and call twice if you want to search two.
</Warning>

You don't need to remember any of this syntax when talking to an AI assistant — just name the library:

<CardGroup cols={1}>
  <Card title="Search a Cloud Library" icon="magnifying-glass" iconType="duotone" horizontal>
    "Search the blueeon/linkly-init-example cloud library for material about
    RAG"
  </Card>

  <Card title="See Which Libraries You Have" icon="list" iconType="duotone" horizontal>
    "List the libraries I've linked"
  </Card>
</CardGroup>

***

## Using It in the Desktop App

If you have the Linkly AI desktop app, cloud libraries work with no MCP configuration at all:

* Open **Settings → Libraries**; the **Connected cloud libraries** section lists every library you've linked, with a per-library toggle for whether it's available in Chat
* Mention a cloud library with `@` in the app's Chat and you can search it just like a local library

This section is read-only — linking and unlinking both happen on the web. If the list is empty, go link a library on the web first.

***

## Sharing with Others

A cloud library has three visibility levels, switchable at any time on the library settings page:

| Visibility   | Who can see the details and file list | Who can link and search it        | Listed in Explore and search engines |
| ------------ | ------------------------------------- | --------------------------------- | ------------------------------------ |
| **Public**   | Everyone                              | Any signed-in user                | Yes                                  |
| **Showcase** | Everyone                              | Invited members only              | Yes                                  |
| **Private**  | The owner and invited people only     | The owner and invited people only | No                                   |

**Inviting people**: go to the library settings page → **Sharing** and send an invitation to their email address. Once accepted, they become a reader and can link and search the library from their own account.

<Note>
  **Tightening** visibility (Public → Private, for example) immediately removes
  the links and stars of everyone who isn't a reader, and cannot be undone.
  **Readers who have accepted an invitation are always kept.** The page spells
  out exactly how many relationships will be cleared before you confirm.
</Note>

***

## Quotas and Limits

|                                 | Free          | Pro                         |
| ------------------------------- | ------------- | --------------------------- |
| Cloud libraries you can create  | 1             | 30                          |
| Documents per library           | 500           | 2000                        |
| Libraries you can link          | 1             | 99                          |
| Visibility options              | Private only  | Public / Showcase / Private |
| Cloud search                    | Available     | Available                   |
| Remote tunnel (to your machine) | Not available | Available                   |

**Libraries created on a free account can only be Private**, meaning only you and the people you invite can use them. Publishing openly or building a showcase library requires an upgrade to [Pro](https://linkly.ai/pricing).

Hitting a quota doesn't affect what's already there — existing libraries and documents you've already pushed are untouched; you just can't create anything new.

***

## FAQ

<AccordionGroup>
  <Accordion title="Is content pushed to the cloud secure?">
    Only the libraries you explicitly push are uploaded. Document text, vectors, and metadata are encrypted in transit and at rest on the server, and visibility is entirely under your control — Private by default. When you no longer want the content in the cloud, deleting the cloud library removes all of it.
  </Accordion>

  <Accordion title="Do the cloud and local copies stay in sync automatically?">
    Not in real time. By default you click **Push** yourself; with **Auto sync**
    turned on, the app checks for changes every 5 minutes and pushes them
    automatically. The cloud copy mirrors the local one, and the direction is
    one-way — content can't be edited in the cloud.
  </Accordion>

  <Accordion title="Why can't my AI assistant find my own library?">
    The usual reason is that **Link** was never clicked. Search scope follows the
    link relationship rather than ownership, so your own libraries need one click
    on **Link** on the library page too.
  </Accordion>

  <Accordion title="My AI assistant says it can't find a cloud:// library?">
    You're most likely connected to the **local** MCP server (`127.0.0.1:60606`,
    server name `linkly-ai`). Cloud libraries are unreachable on that path. Add a
    separate connection to the cloud gateway: URL `https://mcp.linkly.ai/mcp`,
    server name `linkly-ai-cloud`. The two can coexist.
  </Accordion>

  <Accordion title="If I unbind or delete the local library, does the cloud copy disappear?">
    No. Unbinding only stops pushing; the cloud content is kept and you can
    re-bind at any time. To delete the cloud copy, you have to do it explicitly on
    the web, under the library settings page → **Danger zone**.
  </Accordion>

  <Accordion title="Does a library someone shared with me count against my library quota?">
    No. Creation and linking are two separate quotas: someone else's library only takes up one of your **link slots** and never counts toward the libraries you can create.
  </Accordion>
</AccordionGroup>

***

## Further reading

* [Cloud Library Setup for Agents](/docs/en/library-setup) — hand the whole connection process to your AI assistant
* [Using Libraries](/docs/en/use-libraries) — creating local libraries and searching by library
* [Remote Access](/docs/en/use-in-remote) — let cloud AI reach back into the documents on your machine
* [Tools Introduction](/docs/en/tools-intro) — full parameter reference for the retrieval tools