Installing the Agent

The Files.com administrator creates the Agent Remote Server and chooses the file access it should provide. The host administrator installs its binary and configuration, grants the service account access to the intended storage, and runs it as a system service. Both parts are needed before a Mount or Sync can use the connection.

Check the deployment requirements first. In particular, allow the required outbound traffic, prepare a cache on the same volume as the Agent root, and make network shares available to the service account after a restart. Direct Transfers adds separate, optional inbound connectivity.

Creating a Remote Server

Create a new Remote Server and select Files.com Agent from the list of available remote server types.

Enter a name for this connection. This internal name is only used to reference this connection to this Agent.

Select the permissions for file access through the Agent. These permissions determine which file operations Files.com can perform through Remote Mounts, Syncs, and other file transfers.

Write only blocks downloading file contents from the Agent. Listing folders and changing files are separate operations, so Files.com can still replace, rename, and delete existing files. This lets Files.com manage destination files without retrieving their contents.

Enter the full path of a root folder for the Agent. Use a path that exists on the host system. This setting specifies the top-level folder exposed through the Agent for file access. The Agent can access files and folders within this root folder, subject to its configured permissions and the operating-system account's access. File access through the Agent extends to linked locations outside this root folder only when you enable Follow links.

If you also configure Agent Compute commands, review their permissions separately. Programs launched by Agent Compute use the Agent account's operating-system permissions; these file-transfer settings do not confine those programs to the root folder or limit them to read-only work.

Preparing the Configuration

Download the Agent configuration file from the Agent Remote Server settings. Review its root folder and file permissions before installation. The file contains the private key that authenticates this Agent; protect it as you would a password.

Place the binary and configuration file together for initial installation. The active configuration location depends on the installation method, as described below and in Configuration File Location. Stop the service before changing its active configuration, then restart it to load the changes.

Windows

Windows Downloads

• Intel x86 64bit (MSI) (EXE)
• ARM 64bit (EXE)
• Intel x86 32bit (EXE)

Before you install the Agent as a Windows service, make sure that the root setting in the configuration file uses either a local drive path (for example, C:\path\to\folder) or a UNC path to an accessible network drive (for example, \\servername\c$\path\to\folder).

Microsoft advises using UNC paths instead of mapped network drives for system services, so make sure to follow that recommendation for best results.

MSI Based Service Installation

If you're using a Windows x86 64-bit system, you can download the Agent Installer MSI executable.

Use the MSI specifically when you want to install the Agent as a system service. If you plan to run the Agent manually before setting it up as a service, be sure to download and use the EXE version instead.

Place the MSI file in the same folder as the Agent configuration file before installation. Once you've updated the configuration file, run the MSI to install the Agent as a service.

After installation, the active configuration file is the copy at C:\Users\<username>\AppData\Roaming\Files.com-Agent\files_agent_config.toml, where <username> is the account of the person who ran the installer. The installer copies the file there because Windows restricts that folder to one user, which protects the private key inside the file. The Agent Configuration File page covers how to locate the file when someone else installed the Agent.

To uninstall the service, open the Windows "Add or remove programs" app and remove the Agent from there.

Command Line Service Installation

For the EXE download, extract the archive and place files-agent.exe in a folder listed in your %PATH% environment variable. You can then install the Agent as a Windows service using the command:

files-agent.exe service install --config C:\path\to\files_agent_config.toml

When you install the Agent this way, the executable and configuration file stay in their current locations. After installation, open the Windows Services app, locate the "Files.com Agent v2" entry, right-click it, and select Start to begin running the service.

You can also start the service from the command line by running:

files-agent.exe service start

If you need to update the configuration file, stop the service first, make your changes, and then restart the service.

To stop it via the command line, use:

files-agent.exe service stop

To remove the Agent service from the system, run:

files-agent.exe service uninstall

Windows Service Account

Run the Files.com Agent under a dedicated user account, not the default LocalSystem account. LocalSystem carries extensive privileges across the machine, well beyond what the Agent needs. Limit the dedicated account to the directories and network shares the Agent uses; do not reuse a human user's account or grant administrative rights.

For most environments, use a named Active Directory account that can access both the Agent host and any remote system referenced by the root's UNC path. If you use a local user account instead, ensure the same account exists and has appropriate access on both systems. Grant only the read, write, update, and delete permissions the Agent's work requires. The Agent can access only the root items that this account has permission to access.

In the Windows Services management console (services.msc), open the service's properties, select the Log On tab, and configure it to log on as this account. The account must have the "Log on as a service" privilege or the service cannot start.

Manage Password Policies

Apply a strong password policy to the service account. Rotate the password on a regular cadence and do not set it to never expire. Where the environment supports it, use a Managed Service Account (MSA) or Group Managed Service Account (gMSA) so Windows handles password rotation automatically.

Monitor and Audit Service Account Activity

Audit the service account's login attempts and resource access through Windows auditing, and review the logs on a regular schedule. Unexpected logons, access to directories outside the Agent's normal scope, or activity outside expected hours are signals to investigate.

Document Configuration Details

Record the account's assigned permissions, password rotation schedule, and any configuration changes. This record is what you reference during audits, when handing the Agent off to another administrator, or when diagnosing a permission-related failure.

Windows Service Recovery Options

When you install the Agent as a service, it's set to restart automatically if it fails. You can confirm this setup in the "Recovery" tab of the service's properties.

Linux

Linux Downloads

Package installers for Debian, Ubuntu, Linux Mint, Kali, and other Debian based linux systems:

• Intel x86 64bit (.deb)
• ARM 64bit (.deb)

Package installers for Red Hat Enterprise Linux (RHEL), Fedora, CentOS, openSUSE, Amazon Linux, and other Red Hat based linux systems:

• Intel x86 64bit (.rpm)
• ARM 64bit (.rpm)

Package installers for Alpine Linux:

• Intel x86 64bit (.apk)
• ARM 64bit (.apk)

Standalone binaries for all Linux distributions:

• Intel x86 64bit (.tar.gz)
• ARM 64bit (.tar.gz)

Installing the Linux Binary

Download and install the Agent using the package that corresponds to your Linux distribution.

For Debian ARM based 64-bit systems, install the Agent using the following command:

sudo dpkg -i files-agent_linux_arm64.deb

For Debian x86 based 64bit systems, install the Agent using the following command:

sudo dpkg -i files-agent_linux_x86_64.deb

For Fedora ARM based 64bit systems, install the Agent using the following command:

sudo rpm -i files-agent_linux_arm64.rpm

For Fedora x86 based 64bit systems, install the Agent using the following command:

sudo rpm -i files-agent_linux_x86_64.rpm

For Alpine Linux ARM based 64bit systems, install the Agent using the following command:

sudo apk add files-agent_linux_arm64.apk

For Alpine Linux x86 based 64bit systems, install the Agent using the following command:

sudo apk add files-agent_linux_x86_64.apk

After installation, the Agent binary will be available at /usr/local/bin/files-agent. Use the Agent binary to install the Agent as a system service.

Installing the Linux Service

Before you install the Agent as a service, make sure that the root setting in the configuration file uses either a local drive path (for example, /path/to/folder) or a path to an accessible mounted network drive (for example, /mnt/path/to/folder).

To install the Agent as a service on a Linux system, run the following command:

files-agent service install --config /path/to/files_agent_config.toml

Start the service with:

files-agent service start

If you modify the configuration file, stop the service, make your updates, and then restart it.

To stop the service, use:

files-agent service stop

When you're ready to remove the Agent service, run:

files-agent service uninstall

Alternative Installation Method for Linux

If your Linux system uses the systemd init system, you can install the Agent service by creating a service file. For Linux variants that use another init system, refer to the system's init documentation.

Create a file at /lib/systemd/system/files-agent.service with the following content:

[Unit]
Description=Files.com Agent v2
ConditionFileIsExecutable=/usr/local/bin/files-agent

[Service]
StartLimitInterval=5
StartLimitBurst=10
ExecStart=/usr/local/bin/files-agent "start" "--config" "/path/to/files_agent_config.toml" "--log_file" "/path/to/files-agent.log"
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target

Replace the ExecStart paths (config file and log file) with the correct locations for your configuration and log files.

After creating the service file, install and enable it using:

sudo systemctl enable files-agent

Start the service with:

sudo systemctl start files-agent

If you need to update the configuration file, stop the service first, make your changes, and then restart the service.

Stop the service with:

sudo systemctl stop files-agent

Remove the service with:

sudo systemctl disable files-agent

Mac

MacOS Downloads

• Intel x86 64bit (binary)
• Apple Silicon ARM 64bit (binary)

Installing the Mac Binary

Download the Agent zip file that corresponds to your Mac system architecture.

Extract the zip contents and place files-agent into one of the folders listed in your $PATH environment variable. Use the Agent binary to install the Agent as a system service.

Installing the Mac Service

Before you install the Agent as a service, make sure that the root setting in the configuration file uses either a local drive path (for example, /path/to/folder) or a path to an accessible mounted network drive (for example, /mnt/path/to/folder).

To install the Agent as a Launchd service on a Mac, use this command:

files-agent service install --config /path/to/files_agent_config.toml

This method keeps the executable and configuration file in their original locations.

Start the service with:

files-agent service start

If you update the configuration file, stop the service, make your changes, and restart it.

Stop the service with:

files-agent service stop

Remove the service with:

files-agent service uninstall

Verifying the Installation

The Agent connects to Files.com to register its current status. To confirm the status of the Agent, review the Remote Server configuration for the Agent. When multiple nodes serve the Remote Server for Agent High Availability, each node reports its own status, role, availability, versions, and connection health. The following fields show the Agent status information:

On the host, run files-agent service verify to check the installed service and its upload cache. On Windows, open PowerShell or Command Prompt as an administrator. On Linux or macOS, use sudo for a root-owned service and omit it for a user-owned service. Correct any reported configuration, permissions, or cache problem before using the connection.

A Connected status establishes connectivity; it does not establish that the service account can perform every intended file operation. Use Browse to check the configured storage, then create a Remote Server Mount for access to the existing files or a Sync for a separate copy. Test the actual read and write operations your workflow needs, using sample files, and inspect the Agent logs if an operation fails.

Multiple Agents on One Host

Using multiple Agents on the same system is discouraged and can result in excessive license charges at renewal. Each Agent consumes a separate license, even when running on the same machine. Do not install multiple Agents without first confirming that this use fits within the terms of your Files.com subscription.

You do not need multiple Agents to have multiple separate folders synced or mounted on Files.com. When creating a Sync or Remote Server Mount, you specify the remote path for that specific sync or mount. Set the root path for your one Agent to a parent path of the folders you want to access on Files.com.

Running multiple Agents on a single host is technically possible. On Windows-based systems, only one Agent can run as a system service; the others must run manually.

Use Cases

The primary use case for running multiple Agents on a single server is when you have multiple Files.com sites and each site needs access to the same local server.

Another use case is when a Production instance and a Test/Dev instance both connect to the same server. We recommend keeping Production and Test/Dev instances on separate servers, with a dedicated Agent on each, whenever possible.

Procedure for Installing Multiple Agents

Create each Agent as described in the setup instructions. Each Agent must be created on the corresponding Files.com site that you want the Agent to connect with.

Configuring Agents as System Services

On Windows-based systems, you can run multiple Agents manually from the command line. You can also run one Agent as a Service, but the others must run manually from the command line.

On Linux and Mac-based systems, you can run multiple Agents manually from the command line. You can also run multiple Agents as system services by adding one entry per Agent in the Systemd or Launchd configuration.