> For the complete documentation index, see [llms.txt](https://docs.couchdrop.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.couchdrop.io/storage/local-storage.md).
# Local Storage
Learn how to connect Couchdrop to a Windows or OSX File Server
## Overview
Couchdrop can connect to file storage hosted on Microsoft Windows or Apple macOS using the Couchdrop agent.
The agent can run on the file server itself, another server, or a virtual machine. It authenticates to Couchdrop using an **Agent Token** and communicates with Couchdrop over secure HTTPS connections.
Where possible, install the agent on a separate virtual machine and connect the required file storage using mapped network drives rather than installing the agent directly on the target file server.
### How the agent works
The Couchdrop agent provides the connection between Couchdrop and storage accessible from the machine where the agent is installed.
The agent:
* Authenticates using the **Agent Token** generated in Couchdrop
* Communicates with Couchdrop over secure HTTPS connections
* Can run directly on a server or on a separate virtual machine
* Can access file storage exposed to that machine, including mapped network drives
Using a separate virtual machine can keep the Couchdrop agent isolated from the target file server while still providing access to the required storage.
## How to connect a Windows or macOS server
{% hint style="warning" %}
#### Before you start
To connect a Windows or macOS server, you will need:
* Administrator access to the server or a suitable virtual machine
* Remote access to the server, such as RDP for Windows
* A reliable internet connection
* At least 16 GB of memory and 2 CPU cores on the host or virtual machine
* Windows 10 or above when using Windows
* Access to the folder or mapped network drive that Couchdrop will use
For the complete host requirements, see [**Server Requirements**](/storage/local-storage/server-requirements.md).
{% endhint %}
{% stepper %}
{% step %}
### Add a new connection
In Couchdrop, add a new connection and select **Windows/OSX Server** from the list of available connections.
Enter a **Name for this integration** and select the **Couchdrop folder path** where the connection will appear.
{% endstep %}
{% step %}
### Generate your Agent Token
Click **Generate Agent Token**.
Copy the generated token before leaving the page.
{% hint style="danger" %}
The **Agent Token** can only be viewed once. Copy and store it securely before leaving the configuration screen.
{% endhint %}
{% endstep %}
{% step %}
### Download the Couchdrop agent
Download the agent that matches the system where it will run:
* **Windows**
* **OSX x64**
* **OSX arm64**
Log in to the target server or virtual machine using an administrator account, then install and launch the agent.
{% hint style="info" %}
We recommend running the Couchdrop agent on a separate virtual machine where possible, then connecting your file server through mapped network drives.
{% endhint %}
{% endstep %}
{% step %}
### Connect the agent to Couchdrop
Paste the **Agent Token** you generated in Couchdrop into the agent configuration and click **Connect**.
After the connection is established, the agent status should show that the server is connected to Couchdrop.
{% endstep %}
{% step %}
### Test and save the connection
Return to Couchdrop and test the connection.
Once Couchdrop confirms that the agent is connected, save the connection configuration.
You can optionally apply **Transfer Shield**.
Transfer Shield can surface or block unexpected, non-compliant, or malicious files uploaded through the connection. Select a **content rule group** if you want Transfer Shield controls applied.
{% endstep %}
{% endstepper %}
***
## Frequently asked questions
Should I install the Couchdrop agent directly on my file server?
Where possible, no. We recommend installing the agent on a separate virtual machine and connecting the required file storage through mapped network drives.
Which operating systems are supported?
The agent supports Microsoft Windows and Apple macOS. Couchdrop provides downloads for **Windows**, **OSX x64**, and **OSX arm64**.
For Windows systems, Windows 10 or above is required.
Can I connect a mapped network drive?
Yes. The recommended deployment is to run the agent on a suitable virtual machine and connect the target file storage using mapped network drives.
Can the agent connect through a proxy server?
Yes. If internet access is only available through a proxy, you can configure HTTP, HTTPS, or SOCKS proxy details in the Couchdrop Cloud Connector configuration.
Proxy settings and shortcuts to the configuration files are also available from the agent **Settings** menu.
See **Proxy configuration** for configuration examples.
Does the agent require inbound firewall ports?
No. The Couchdrop agent communicates with the Couchdrop control plane and APIs over HTTPS, so additional inbound ports do not need to be opened.
If your organization restricts outbound traffic using a firewall, proxy, or web filter, you may need to allow the Couchdrop domains and addresses listed under **Server Requirements**.
How does the agent authenticate with Couchdrop?
The agent uses an **Agent Token** generated when configuring the connection in Couchdrop.
The token can only be viewed once, so copy and store it securely when it is generated.
How does the agent authenticate with Couchdrop?
The agent authenticates using an **Agent Token** generated when you configure the **Windows/OSX Server** connection in Couchdrop.
The token can only be viewed once. Copy and store it securely before leaving the configuration screen.
Where can I find the Couchdrop agent logs?
On Windows, the agent logs are stored by default in:
```
C:\Users\%username%\AppData\Local\CouchdropCloudConnector
```
You can also open the local logs and configuration files from the **Settings** gear within the Couchdrop agent.
See [**Logging and Debugging**](/storage/local-storage/logging-and-debugging.md) for more information.
---
# 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.couchdrop.io/storage/local-storage.md?ask=&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.