Choose an Agent host that stays available during the access and transfer windows your workflows require. Its operating system, storage, service-account permissions, and outbound network access determine whether Files.com can reach the intended files. Prepare these before installing the Agent.

Host Requirements

The Files.com Agent is supported on Windows (64-bit and 32-bit), Linux (64-bit), and MacOS (64-bit).

For 64-bit Windows based systems, only the following operating systems are supported:

Windows Server 2016 (EOL Jan 12, 2027)
Windows Server 2019
Windows Server 2022
Windows Server 2025
Windows 10 (EOL Oct 14, 2025)
Windows 11

The 32-bit Windows Agent binary is supported on the following operating systems, including Windows Server 2016 running the 32-bit application on a 64-bit OS:

Windows Server 2016 (EOL Jan 12, 2027)
Windows 10 Enterprise (EOL Oct 14, 2025)

The Agent is a very lightweight application, requiring minimal system resources.

The Agent is self-contained, does not have any external dependencies, and does not require any external system libraries or helper applications.

There are no minimum specifications for system CPU or Memory and the Agent will run on systems ranging from high-end enterprise servers to low-cost single-board computers, such as a Raspberry Pi.

Agent Resource Usage Metrics

	Idle	Under Heavy Load
CPU Use	0%	Varies, depending on load and CPU size. Tests using an Intel Xeon CPU E5-2673 v4 @ 2.30GHz showed occasional peaks between 20% and 50%.
MEM Use	Approx. 13 MB	Approx. 50 MB
Disk Use	Approx. 40 MB (Agent binary) plus 100 MB (logs)	Approx. 40 MB (Agent binary) plus up to 1 GB (logs)

The disk figures above cover the binary and logs. Allow additional space for the Agent's upload cache, based on the files and concurrent transfers it handles.

Enterprise Support For Mainframes and Other Operating Systems

The following additional OS and CPU combinations can also be made available for the Files Agent, but require manual configuration of our build process.

If you are interested in running the Files Agent on any of the following system architectures, please let us know. We'd be happy to make the required version available for you.

aix/ppc64 - AIX on PowerPC 64-bit (big-endian)
dragonfly/amd64 - DragonFly BSD on 64-bit x86-64
freebsd/386 - FreeBSD on 32-bit x86
freebsd/amd64 - FreeBSD on 64-bit x86-64
freebsd/arm - FreeBSD on 32-bit ARM
freebsd/arm64 - FreeBSD on 64-bit ARM (AArch64)
freebsd/riscv64 - FreeBSD on RISC-V 64-bit
illumos/amd64 - Illumos on 64-bit x86-64
linux/386 - Linux on 32-bit x86
linux/amd64 - Linux on 64-bit x86-64
linux/arm - Linux on 32-bit ARM
linux/arm64 - Linux on 64-bit ARM (AArch64)
linux/loong64 - Linux on LoongArch 64-bit
linux/mips - Linux on MIPS 32-bit (big-endian)
linux/mips64 - Linux on MIPS 64-bit (big-endian)
linux/mips64le - Linux on MIPS 64-bit (little-endian)
linux/mipsle - Linux on MIPS 32-bit (little-endian)
linux/ppc64 - Linux on PowerPC 64-bit (big-endian)
linux/ppc64le - Linux on PowerPC 64-bit (little-endian)
linux/riscv64 - Linux on RISC-V 64-bit
linux/s390x - Linux on IBM Z (s390x) 64-bit
netbsd/386 - NetBSD on 32-bit x86
netbsd/amd64 - NetBSD on 64-bit x86-64
netbsd/arm - NetBSD on 32-bit ARM
netbsd/arm64 - NetBSD on 64-bit ARM (AArch64)
openbsd/386 - OpenBSD on 32-bit x86
openbsd/amd64 - OpenBSD on 64-bit x86-64
openbsd/arm - OpenBSD on 32-bit ARM
openbsd/arm64 - OpenBSD on 64-bit ARM (AArch64)
openbsd/ppc64 - OpenBSD on PowerPC 64-bit (big-endian)
openbsd/riscv64 - OpenBSD on RISC-V 64-bit
plan9/386 - Plan 9 on 32-bit x86
plan9/amd64 - Plan 9 on 64-bit x86-64
plan9/arm - Plan 9 on 32-bit ARM
solaris/amd64 - Solaris on 64-bit x86-64

Upload Cache

When the Agent transfers files, uploads write parts to a local cache on the host machine before finalizing. The storage backing that cache directly affects upload throughput. On a VM whose primary storage is network-attached, this requires deliberate planning before deployment.

How the Agent Caches Uploads

Buffering only applies to uploads. Downloads do not use a local cache.

When the Agent receives an upload, it breaks the file into parts and stores each completed part in a FilePart cache on the host file system. Once all parts arrive, the Agent streams them into the final file in sequence, deleting each cached part as it is written. Each running Agent worker cleans up only its own cached data while it works, and leftover data from workers that have stopped, including after an unexpected exit, is removed separately. Several workers can share one cache location safely, because the Agent keeps each worker's temporary data separate automatically.

Parallel part uploads are enabled by default (upload_parallel_parts = true). This is what drives the cache requirement: with parallel parts enabled, multiple parts accumulate in the cache simultaneously during large or concurrent uploads. If the Agent cannot build a valid same-volume cache, it logs the error and falls back to sequential uploads for that run.

Cache Storage Location

The upload_temp_file_part_path setting in the Agent configuration file controls where the FilePart cache is written. The path must be absolute and on the same filesystem volume as the Agent root (root).

Keeping the cache and the root on the same volume matters for finalization. When both are on the same volume, the Agent can stream each part directly into its final location without a cross-volume copy. When they are on different volumes, finalization copies every part across the volume boundary. If the root is on a NAS, that boundary is the network.

If upload_temp_file_part_path is not set, the Agent uses the OS default temporary file location, which may be on a different volume from the root.

Local disk (direct-attached storage) is strongly recommended for both the Agent root and the cache. SAN volumes attached via fiber channel are also acceptable. NAS storage (CIFS/SMB or NFS) is strongly discouraged. Network latency in the cache path adds overhead to every part the Agent writes and reads, degrading upload throughput across all concurrent transfers.

If NAS is the only available option for the Agent root, set upload_temp_file_part_path to a path on the same NAS volume rather than leaving it unset. Leaving it unset risks landing the cache on the system drive, which forces a cross-volume network copy for every part during finalization. When root and cache are on the same NAS volume, finalization avoids that extra copy, though overall throughput will still be lower than a local-disk deployment.

To verify the cache path on a deployed Agent, run files-agent service verify. If it warns about the FilePart cache path, set upload_temp_file_part_path explicitly.

On Windows, run the verification from PowerShell or Command Prompt opened as an administrator. On Linux or macOS, use sudo files-agent service verify for a root-owned system service and omit sudo for a user-owned service.

If Files.com reports that the upload cache is unavailable, confirm that the configured directory exists and that the Agent service account can create, write, and delete files there. If Files.com reports that the cache is on the wrong volume, move it to the same filesystem volume as the configured Agent root. Uploads continue with lower performance while the Agent uses its fallback upload path.

Restart the Agent after correcting the cache path because it selects the cache when it starts. Run files-agent service verify again after the restart. The site warning clears after the Agent reconnects and reports the corrected cache state.

Sizing the Cache

The cache is transient. Parts are deleted as they are written during finalization, each worker cleans up its own data as it goes, and leftover data from stopped workers is removed separately. The disk space requirement at any given moment depends on how many concurrent uploads are in progress and how large those files are.

Use these guidelines when provisioning the volume that hosts the Agent root and cache:

Scenario	Free Space Guidance
Basic install and logs	1 GB
Normal production use	5 GB
Recommended production buffer	20 GB, or 10% of free disk, whichever is larger
Large uploads	At least the size of the largest expected in-flight upload; 2× is preferred

Available space on the root volume matters more than total system disk space, because the cache must reside on the same volume.

Low-Space Warning

The Agent warns your Files.com site when the root volume has 1 GiB or less available. It also warns when the volume has 10% or less available and no more than 10 GiB remains.

Free space or expand the root volume until neither limit applies. The Agent checks the volume periodically and clears the warning after it reports enough free space. You do not need to restart the Agent.

Symlinks and Windows Shortcuts Inside the Mount Path

The Agent does not follow symlinks or Windows shortcuts by default. To allow the Agent to access storage locations pointed to by symlinks or shortcuts within the mount path, set follow_links = true in the Agent configuration file.

With Follow Links enabled, the Agent traverses the OS path to the backing storage transparently. Cache behavior is unchanged: the Agent always writes to upload_temp_file_part_path regardless of whether the transfer source or destination is a direct path or a symlink target. The sizing and storage location recommendations above apply in either case.

The performance of reads and writes to a symlinked path is governed by the backing storage of the symlink target. A symlink that points to a slower NAS share within an otherwise fast mount path will be limited by that NAS share's throughput.

Network Requirements

The Agent makes outbound-only connections to Files.com over encrypted connections. It operates inside typical enterprise firewall and NAT environments without inbound rules, port forwarding, or exposing internal systems to the public internet.

The Agent uses port 8801 for data transmission and separate connections for DNS lookups. It does not require any inbound network ports. The Direct Transfers feature is the one exception, adding an optional inbound listener for increased data transmission throughput with the Files.com CLI App and Desktop App.

Data Transmission

The Agent uses a single outbound network port, port 8801, for data transmission. This port cannot be customized.

The Agent uses both the UDP and TCP protocols. It first attempts to connect over the faster UDP protocol and falls back to TCP if UDP is unavailable.

The Agent connects to Files.com using the general pool of Files.com IP addresses. Make sure that outbound connections to these IP addresses using port 8801 are allowed through your firewall.

If your Files.com site uses a custom domain, the Agent connects using your dedicated IP addresses instead.

DNS Lookup

By default, the Agent tries DNS over HTTPS at https://cloudflare-dns.com on TCP port 443. If that fails, it falls back to the host's system resolver.

Allow access to the DNS service selected in the Agent configuration. System DNS normally uses port 53, not port 443. The dns_server setting can specify a different resolver and port. Setting dns to system skips DNS over HTTPS; setting it to doh uses DNS over HTTPS without the system fallback.

Direct Transfers

When Direct Transfers are enabled, allow inbound TCP and UDP connections to the Agent host on the listener ports, which default to 4001 through 4010, and forward each public port to the same port number on the Agent host. The port range and the rest of the listener configuration are set in the Agent configuration file.

When multiple nodes serve the Remote Server for Agent High Availability, every node's host needs inbound rules and port forwarding, and Direct Transfers covers how the port numbers relate across nodes. Clients connect to whichever node is handling their transfer, and a node whose ports stay closed serves its transfers over the standard connection route instead.

Deployment Requirements