> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/integrations/connecting-your-file-server.md).

# Connecting your file server

How an admin installs Cogram Connector to make Windows file shares or a LucidLink filespace available in Cogram.

Cogram Connector is a small Windows service that you install in your own network. It connects your file servers or your LucidLink filespace to Cogram as an organization-level integration. After setup, your team can browse the shares on the [Files](https://app.cogram.com/dashboard/files) page, search file names and file content, and preview files. [Agent](https://docs.cogram.com/agent/agent.md) can also read these files to answer questions.

This page is for the organization admin and the IT administrator who do the setup. For what your team sees day to day, read [Your file server](https://docs.cogram.com/projects/file-server.md).

## How it works

* Cogram Connector runs on a Windows server in your network. It reads your shares with a service account that you select. Cogram never receives file-server credentials.
* Cogram Connector builds a search index locally, on that host. The index and your files stay in your network.
* Cogram Connector makes one outbound HTTPS connection (port 443) to Cogram. There are no inbound connections. You do not open firewall ports.
* Only the data that a user asks for goes to Cogram: search results, and the content of the files that they open. Diagnostic error reports are a separate opt-in.
* Permissions come from one of two sources. You select the source when you create the connector:
  * **Windows file shares**: Active Directory permissions. You map each Cogram user to their AD account on the **Identity & access** page. Cogram Connector returns only the files that this account can read, under both the share permissions and the NTFS permissions.
  * **LucidLink**: your filespace permissions. You map each Cogram user to their LucidLink member. Refer to [Connect a LucidLink filespace](#connect-a-lucidlink-filespace).
* A user without a mapping sees no files.
* Cogram Connector is read-only unless you enable uploads. Refer to [Allowing uploads](#allowing-uploads-optional).

## Prerequisites

* You are a Cogram organization admin.
* You have a domain-joined Windows Server that can reach your file shares. The file server itself is a good host.
* You have a service account (a regular domain account or a gMSA) that can read every folder that you want to make searchable, and its password. A gMSA has no password.
* The server can make outbound HTTPS connections (port 443) to `app.cogram.com`.
* Your Cogram users sign in with the same email address that is on their AD account (the `mail` or `userPrincipalName` attribute). Cogram uses this address to suggest the mapping for each user. You confirm the suggestions.

For a LucidLink filespace, the prerequisites are different. Refer to [Connect a LucidLink filespace](#connect-a-lucidlink-filespace).

## Set up Cogram Connector

1. Go to [Organization Settings → Integrations → File Server Connectors](https://app.cogram.com/dashboard/settings/admin/integrations#connectors) and select **Cogram Connector – File Server**.
2. Under **Where do permissions come from?**, select **Windows file shares** or **LucidLink**.
3. Enter a name (for example "Engineering file server") and an optional description. Select **Create connector**.
4. Copy the **enrollment token** and store it in a safe place. Cogram shows the token only one time. If you lose the token, delete the connector in Cogram and create a new one.

The next page shows the setup steps for the source that you selected. If you selected the wrong source, select the link under the install command (**Using LucidLink instead?** or **Using Windows file shares instead?**). The page has these steps:

* **What you'll need**: a checklist of the prerequisites.
* **1. Download and unzip on that machine**: select **Download connector**. Copy the ZIP file to the Windows server and unzip it.
* **2. Install**: open PowerShell as administrator in the unzipped folder. Copy the install command, replace the example values, and run it. The token and the backend URL are pre-filled.
* **3. Check that it's working**: come back to the Cogram Connector page. Refer to [What good looks like](#what-good-looks-like).
* **4. Give people access**: map each user on **Identity & access**. Refer to [Map users to AD accounts](#map-users-to-ad-accounts).

For Windows file shares, the install command looks like this:

```powershell
.\install.ps1 `
  -Token "cn_xxx.secret" `
  -BackendUrl "https://app.cogram.com" `
  -SharePaths "\\your-server\share-one;\\your-server\share-two" `
  -ServiceAccount "DOMAIN\svc-cogram"
```

| Flag              | What it means                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-SharePaths`     | The shares to index, separated by `;`. Start with one project folder. The first index of a large server can take hours.                                                                                                                                                                                                                                                                                             |
| `-ServiceAccount` | The account that Cogram Connector runs as, in the form `DOMAIN\name`. End a gMSA name with `$`.                                                                                                                                                                                                                                                                                                                     |
| `-IndexDir`       | Optional. Where to keep the search index, for example `"D:\Cogram\Index"`. The index can grow to tens of GB, so you can keep it off the system drive. Use an empty or new folder on a local disk of this server, not a network path, a mapped drive, or a drive root. A reinstall keeps the current index folder. To move it later, refer to [Change settings after installing](#change-settings-after-installing). |

The installer then asks for the password of the service account. Type it at the prompt, so that it stays out of PowerShell history. A gMSA has no password, so the installer does not ask.

The script registers and starts the `CogramConnector` Windows service. The service starts to index your shares immediately.

### What good looks like

Go back to [Organization Settings → Integrations → File Server Connectors](https://app.cogram.com/dashboard/settings/admin/integrations#connectors). Within a minute, the status line under the connector name shows **Connected · Building index… X of Y files** and **Permissions from Windows** (or **Permissions from LucidLink**). Search works while the index builds. The list of crawled shares fills with file counts and sizes. When indexing completes, the status shows **Index ready**. The first pass on a large file server can take a while. Later passes read only the changed files.

Until you map your users, the page shows **No one can see files yet**. Continue with the next section.

## Map users to AD accounts

Cogram Connector runs every request as the AD account of the Cogram user who makes it. No user has access until you map them. Open **Identity & access** on the Cogram Connector page, or select **Map people** in the notice at the top of the page:

1. Each Cogram user shows one of five states. **Suggested**: exactly one AD account carries the user's email address. **Mapped**: you confirmed an account. **Multiple matches**: more than one AD account carries the email address. **No match**: no AD account carries it. **Account in use**: the matching account is already mapped to another user, or carries two users' addresses. Decide who gets it.
2. Select **Map all suggested** to confirm every suggestion in one step. Or select **Map** next to one user.
3. For a user with **Multiple matches** or **No match**, select **Choose** and pick the account from the directory. You can search by name, login, or email address.
4. To change a mapping, select **Change**. To remove one, select **Unmap**. An unmapped user sees no files.

For a LucidLink filespace, you map each user to their LucidLink member instead. Refer to [Map users to LucidLink members](#map-users-to-lucidlink-members).

A mapping is per connector. If you delete the connector and create a new one, map the users again. An AD account that is disabled cannot be mapped. If a mapped account is later disabled or deleted, the user shows **Account disabled** or **Account missing** and gets no files.

Project exports run as the user who saved the export settings for that project. If that user is not mapped, the export waits, and the project shows **Run-as user not mapped** on the [File export](https://docs.cogram.com/integrations/file-export.md) page.

## Verify what users can see

The Cogram Connector page has three checks. Use them before you roll out to your team:

* **Browse files** opens the file server as any user in your organization. Use it to make sure that a user sees only the folders and files that their own account can open.
* **Identity & access** shows each user's mapping and lets you change it.
* **Index health** shows how much of the server the search can read. Files without extracted text are findable by name only.

## Connect a LucidLink filespace

On a LucidLink filespace, the Windows permissions let every signed-in user in. For this reason, Cogram Connector reads the permissions from LucidLink instead. To use this source, select **LucidLink** under **Where do permissions come from?** when you create the connector.

### What you'll need

* The Windows machine where your LucidLink filespace is mounted. Cogram Connector runs on this machine.
* The LucidLink API on that machine. This is LucidLink's self-hosted `lucidlink/lucidlink-api` Docker container. Cogram Connector expects it at `localhost:3003`. If it runs at a different address, add `-LucidLinkUrl` to the install command.
* A LucidLink service account key (`sa_live:…`). Create one in LucidLink's admin console under **Service accounts**.
* A Windows service account that can read the filespace, and its password. A gMSA has no password.
* Outbound HTTPS (port 443) from that machine to `app.cogram.com`.

### Install for LucidLink

Follow the steps in [Set up Cogram Connector](#set-up-cogram-connector). The install command for LucidLink looks like this:

```powershell
.\install.ps1 `
  -Token "cn_xxx.secret" `
  -BackendUrl "https://app.cogram.com" `
  -SharePaths "\\your-filespace.your-workspace\FileSpace\Projects" `
  -ServiceAccount "DOMAIN\svc-cogram" `
  -LucidLinkMountRoot "\\your-filespace.your-workspace\FileSpace"
```

| Flag                    | What it means                                                                                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-SharePaths`           | The folders inside the filespace to index, separated by `;`. Start with one project folder. The first index of a large filespace can take hours.                                                                        |
| `-ServiceAccount`       | The account that Cogram Connector runs as, in the form `DOMAIN\name`. End a gMSA name with `$`.                                                                                                                         |
| `-LucidLinkMountRoot`   | Where the filespace is mounted on this machine. Use the root of the filespace, for example `L:\` or `\\your-filespace.your-workspace\FileSpace`, not a folder inside it. Every path in `-SharePaths` must be inside it. |
| `-IndexDir`             | Optional. Where to keep the search index. The same rules apply as for Windows file shares, above.                                                                                                                       |
| `-LucidLinkUrl`         | Optional. The address of the LucidLink API, if it is not at `localhost:3003`.                                                                                                                                           |
| `-LucidLinkFilespaceId` | Optional. Necessary only if your workspace has more than one filespace and the mount root is not a `\\<filespace>.<workspace>\...` path that names one of them.                                                         |

The installer then asks for the password of the service account and for the LucidLink key. Type them at the prompts, so that they stay out of PowerShell history. Do not put the LucidLink key on the command line.

### Map users to LucidLink members

Open **Identity & access** on the Cogram Connector page and map each Cogram user to their LucidLink member. The steps are the same as in [Map users to AD accounts](#map-users-to-ad-accounts). Cogram suggests a member when the email address matches.

Cogram Connector applies the LucidLink permission rules:

* For each folder, a person and each of their groups get the access of the nearest grant at or above that folder. The person gets the combined access of all of these.
* Workspace admins, and filespace admins of this filespace, see everything.
* A person does not see the folders and files that they cannot read. A folder that only leads to a folder they can read is visible, but nothing else in it is.

### Things to expect with LucidLink

* A permission change in LucidLink takes 5 to 15 minutes to reach Cogram. Cogram Connector refreshes the permissions in the background every 5 minutes, and reloads them when they are older than 15 minutes.
* The match between file paths and LucidLink grants is case-sensitive. A grant on `/Projects` does not apply to a folder named `/projects`.
* If the LucidLink API container stops, Cogram Connector denies access to everyone until the API answers again.

## Alert emails

If Cogram does not hear from Cogram Connector for 15 minutes, nobody can search or open files, so Cogram sends an email: "Action needed: Cogram Connector is offline". Cogram sends it one time for each outage. When the connector is back and stays up for 2 hours, Cogram sends "Resolved: Cogram Connector is back online". If the connector stops again before then, it is the same outage, and you do not get another email.

For a LucidLink connector, Cogram also sends an email if the connector cannot load the LucidLink permissions for 5 minutes: "Action needed: Cogram can't check LucidLink permissions". When the permissions load again, Cogram sends "Resolved: LucidLink permissions are working again".

To choose who gets these emails, enter the addresses in the **Alert email** field on the Cogram Connector page and select **Save**. Only admins can change it.

* Enter up to 5 addresses, usually your IT contact.
* If the field is empty, Cogram emails the admin who created the connector.
* Cogram support gets a copy of each email.
* Cogram checks every 5 minutes, so an email can arrive up to 5 minutes after the problem starts or ends.
* If Cogram itself is down, you do not get an offline email. After Cogram is back, the 15 minutes start again.
* Times in the email use the time zone of the admin who created the connector.

## Allowing uploads (optional)

By default, Cogram Connector never writes to your server. To let users upload files from the Files page, three conditions must all be true:

1. Writes are on for Cogram Connector. Add the `-AllowWrites` switch to the install command. To turn writes on after you installed, run `& "$env:ProgramFiles\Cogram\Connector\configure.ps1" -AllowWrites` on the host. To turn them off, use `-AllowWrites:$false`. Refer to [Change settings after installing](#change-settings-after-installing).
2. The service account has write access to the share: Modify on the folder tree, and Change in the share permissions. Share permissions are separate from NTFS permissions. The stricter of the two applies.
3. The user who uploads the file has write access to the destination folder. Cogram Connector checks that user's access, not its own.

An upload never replaces an existing file. One upload has a limit of 2 GB. The service account owns the uploaded files on disk. Cogram records which user uploaded each file.

The same three conditions govern project export, where Cogram files a project's completed items into a folder you choose. Set it up under [File export](https://docs.cogram.com/integrations/file-export.md). Exports run as the person who last saved a project's export settings, so that account needs write access to the folder.

## Updates

Cogram Connector keeps itself up to date. It downloads the version that Cogram recommends and verifies the code signature. A scheduled task on the host applies the update. If the new version does not start, the task restores the old version and does not try that version again. A newer release installs as usual. You do not need to plan maintenance for updates.

To update manually, download the new version from the Cogram Connector page. Then run `update.ps1` from the unzipped folder on the host. The token, the configuration, and the service registration stay unchanged. The page shows an **Update available** or **Update required** badge when the installed version is behind.

## Change settings after installing

You can change the shares, uploads, the index folder, and the LucidLink key without a reinstall. Use `configure.ps1`, which the installer copies into the install folder. Every update refreshes it there. It needs Cogram Connector 0.14.0 or later.

Open PowerShell as administrator on the host and run one of these commands:

```powershell
& "$env:ProgramFiles\Cogram\Connector\configure.ps1"
& "$env:ProgramFiles\Cogram\Connector\configure.ps1" -AddSharePaths '\\fs01\Projects2'
& "$env:ProgramFiles\Cogram\Connector\configure.ps1" -AllowWrites
& "$env:ProgramFiles\Cogram\Connector\configure.ps1" -IndexDir 'D:\Cogram\Index'
& "$env:ProgramFiles\Cogram\Connector\configure.ps1" -LucidLinkKey
```

| Option           | What it does                                                                                                                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No options       | Shows the current settings. It never shows the token or the LucidLink key.                                                                                                                                      |
| `-AddSharePaths` | Adds shares, separated by `;`. Use `-RemoveSharePaths` to remove them. With LucidLink, every share must be inside the filespace.                                                                                |
| `-AllowWrites`   | Turns on uploads and exports. `-AllowWrites:$false` turns them off.                                                                                                                                             |
| `-IndexDir`      | Moves the search index. Cogram Connector keeps the index, so it does not read your files again. Use an empty or new folder on a local disk of this server, not a network path, a mapped drive, or a drive root. |
| `-LucidLinkKey`  | Asks for a new LucidLink service account key. LucidLink only.                                                                                                                                                   |

The script does not need the service account password. It restarts Cogram Connector with the new settings. If Cogram Connector does not start with them, the script puts the previous settings back and tells you to check Event Viewer (**Windows Logs → Application**) for the reason.

You can change these settings only on the host, not in Cogram. This is intentional: Cogram cannot make Cogram Connector read more folders, or let it write.

To remove Cogram Connector, run `uninstall.ps1` on the host. Then delete the connector in Cogram. Add `-Purge` to also delete the local search index. If you installed with `-IndexDir`, give `uninstall.ps1 -Purge` the same `-IndexDir`.

## Troubleshooting

#### Connector is offline

Cogram shows the connector as **Offline**.

* **Likely cause:** The `CogramConnector` service is stopped, or the host lost its outbound connection.
* **Fix:** On the host, check the service in `services.msc` and start it. Your files are not affected while Cogram Connector is offline. The page shows **Offline** as soon as the service stops.

#### Not everyone is mapped

The Cogram Connector page shows **No one can see files yet** or **N of M people mapped**.

* **Likely cause:** Some Cogram users are not mapped to an AD account or a LucidLink member.
* **Fix:** Select **Map people** and map the remaining users.

#### Folders could not be read

The Cogram Connector page shows **N folders couldn't be read**, with example paths.

* **Likely cause:** The service account cannot read these folders. Cogram Connector skips them, so their files are missing from search.
* **Fix:** Give the service account read access to these folders. Cogram Connector picks them up on the next pass.

#### LucidLink: no user sees files

With LucidLink, no user sees any files.

* **Likely cause:** The LucidLink API container on the host is stopped or cannot be reached. Cogram Connector then denies access to everyone.
* **Fix:** Start the `lucidlink/lucidlink-api` container on the host. If it runs at an address other than `localhost:3003`, install again with `-LucidLinkUrl`.

#### LucidLink: access change not applied

With LucidLink, a user still sees a folder after you removed their access, or does not see one after you granted it.

* **Likely cause:** A permission change takes 5 to 15 minutes to reach Cogram.
* **Fix:** Wait 15 minutes, then check again.

#### User cannot see the file server

A user sees "You can't see the file server yet".

* **Likely cause:** No admin has mapped this user to an AD account or a LucidLink member.
* **Fix:** Open **Identity & access** on the Cogram Connector page and map the user.

#### Mapped user sees no files

A mapped user sees no files, or folders that they expect are empty.

* **Likely cause:** The mapped account has no read access, or you mapped the wrong account. With LucidLink, the path in the grant can also differ in case from the folder.
* **Fix:** Check the mapping under **Identity & access**. Permissions come from the file server or from LucidLink. Grant access there, not in Cogram.

#### Lost enrollment token

You lost the enrollment token.

* **Likely cause:** Cogram shows the token only one time, at creation.
* **Fix:** Delete the connector in Cogram and create a new one. Run the installer again with the new token.

#### Upload permission denied

An upload fails with "You do not have permission to add files to this folder."

* **Likely cause:** One of the three write conditions is not met. A missing Change permission on the share is a frequent cause.
* **Fix:** Check all three conditions under [Allowing uploads](#allowing-uploads-optional).

#### Connector did not start

`configure.ps1` says "The Connector did not start with the new settings, so the previous settings are back."

* **Likely cause:** Cogram Connector rejected one of the new settings, for example a share that the service account cannot read.
* **Fix:** In Event Viewer, open **Windows Logs → Application** and find the `CogramConnector` entries for the reason. Correct the setting and run `configure.ps1` again.

#### Application Error in Event Viewer

Event Viewer shows an **Application Error** for `CogramConnector.exe`, but Cogram Connector is still online.

* **Likely cause:** A damaged or unusual PDF stopped the separate process that reads PDF text. Cogram Connector reads each PDF in a process of its own, so the service keeps running.
* **Fix:** No action is needed. That PDF is findable by name. Cogram Connector tries its contents again in a week, or sooner if the file changes.

#### PDF workers are not working

Event Viewer shows the warning "PDF workers are not working".

* **Likely cause:** Security software blocks or stops the processes that Cogram Connector starts to read PDFs. Cogram Connector then reads PDFs more slowly for 30 minutes, and tries again.
* **Fix:** In your security software, allow `CogramConnector.exe` in `C:\Program Files\Cogram\Connector` to start copies of itself.

## Next steps

* [Your file server](https://docs.cogram.com/projects/file-server.md): what your team can do with the connected shares.
* [Agent](https://docs.cogram.com/agent/agent.md) can search and read these files when someone asks it a question.
* [Privacy and confidentiality](https://docs.cogram.com/get-started/privacy-and-confidentiality.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cogram.com/integrations/connecting-your-file-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
