Agent Configuration File
The Agent configuration file contains the settings and credentials that the Agent uses to connect to your Files.com site.
This configuration file contains the private key that authenticates your Agent to your Files.com site. Treat this file the same as a password and do not share it with anyone.
The Files.com Agent configuration file is generated by Files.com when the Remote Server for the Agent is created.
You can download the configuration file for an existing Agent Remote Server from within its Remote Server settings.
The configuration file is TOML formatted so that it is both human-readable and machine-readable. The system administrator edits this file manually to customize the Agent, and to review an Agent's configuration when the Agent was created by someone else.
Configuration File Location
The location of the configuration file depends on how the Agent was installed as a system service.
When the Agent service is installed from the command line on Windows, Linux, or Mac, the configuration file stays wherever it was when you ran the install command. The --config option records that path in the service definition, and the Agent reads the file from there.
When the Agent is installed using the Windows MSI, the active configuration file is 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 configuration file into that location from the folder containing the MSI. Windows restricts that folder to that one user, which protects the private key inside the file.
Older MSI installations placed the configuration file at C:\Program Files\Files.com-Agent\files_agent_config.toml. The Agent reads that location only when the file in the newer location is missing. Do not place new configuration files there, because Windows gives every user on the system read access to the Program Files folder by default, and that access can expose the private key.
When the Agent is installed from a Linux package (.deb, .rpm, or .apk), the standard location for the configuration file is /opt/filescom/files_agent_config.toml.
Finding an Existing Configuration File
When you take over an Agent host and do not know where its configuration file is, ask the installed service. Run the following command on the Agent host. It prints the path of the configuration file that the service loads.
files-agent service config
On Windows, the configuration file for an MSI installation lives in the profile of the person who installed the Agent, so a different administrator needs to run their shell as an administrator to open the file at the printed path.
Configurable Settings
The following settings are intended to be reviewed and adjusted by the system administrator before and during use.
Access and Permissions
These settings control which files and directories the Agent can access on the host system.
| Field | Description |
|---|---|
root | The top-level directory that the Agent has access to. Set this to a directory location on the host system that you want the Agent to access. Make sure that the path is enclosed in single quotes. For example, '/path/to/agent/folder', 'C:\windows\folder', '/mnt/otherserverfolder', or '\\networkservername\c$\folder'. The path location must have the correct access permissions for the user, or service account, that is running the Agent. Network mount locations must be mounted on the host system, with the correct access permissions, prior to use by the Agent. |
permission_set | The permissions the Agent has over its root directory. Your Files.com administrator sets this initially, but the system administrator can change it. Valid options are read_write, read_only, and write_only. |
follow_links | Whether the Agent follows symbolic links, giving it access to linked folders outside of root. Valid options are true or false. The default is false. |
show_hidden_files | Whether the Agent can access hidden files and folders on Windows systems. Valid options are true or false. The default is false. |
validate_root_permissions | Whether the Agent checks that it can read and write its root directory at startup before accepting jobs. Valid options are true or false. The default is true. |
Private Key File
By default, the Agent's private key is stored inline in the configuration file in the private_key field. As an alternative, you can store the key in a separate file and reference it by path.
| Field | Description |
|---|---|
private_key_path | Path to a file containing the Agent's private key. Use this as an alternative to storing the key inline in private_key. Relative paths resolve from the directory containing the configuration file. |
Automatic Updates
The Agent can update itself automatically, manually, or not at all. Use manual_trigger to update the Agent only when triggered manually from your Files.com site. Use always to keep the Agent current automatically. Use critical_only to limit automatic updates to versions that address reliability, performance, or security issues. Use never only when your organization manages all software updates through its own deployment process.
| Field | Description |
|---|---|
auto_update_policy | How the Agent handles available updates. Valid options are always, critical_only, manual_trigger, and never. The default is always. |
Job Concurrency
The Agent processes multiple jobs in parallel. The default concurrency limit is 500. If you see job queue is full errors, the Agent is receiving more work than it can process simultaneously. You can raise override_max_concurrent_jobs to increase the limit, but the right value depends on available memory and I/O capacity. Test under realistic load before committing to a higher value.
| Field | Description |
|---|---|
override_max_concurrent_jobs | The maximum number of jobs the Agent processes simultaneously. The default is 500. |
override_max_completed_jobs | The maximum number of completed job results the Agent retains in memory so Files.com can retrieve them asynchronously. Higher values allow more results to be available after completion but increase memory usage. The default is 100. |
Network Protocol
The Agent connects to Files.com using UDP by default, which is faster and lower-latency than TCP. If the host network blocks outbound UDP, which is common in restrictive corporate or government environments, the Agent falls back to TCP automatically. Set prefer_protocol to tcp to avoid using UDP entirely when you know UDP is blocked.
| Field | Description |
|---|---|
prefer_protocol | The network protocol the Agent uses when connecting to Files.com. Valid options are udp and tcp. The default is udp. |
Direct Transfers
These settings control Direct Transfers, which let the Files.com CLI App and Desktop App send file data straight to the Agent for faster uploads and downloads.
| Field | Description |
|---|---|
direct_transfers | Whether the Agent accepts direct connections from the Files.com CLI App and Desktop App for uploads and downloads. Clients fall back to the standard connection route when the Agent cannot be reached directly. Valid options are true or false. The default is false. |
direct_transfer_port | The local port, or range of ports, the Agent listens on for direct transfers, such as "4001" or "4001:4010". The Agent uses the first free port in the range. A range keeps direct transfers available while the Agent updates itself. The default is "4001:4010". |
direct_transfer_upnp | Whether the Agent asks the local router to open a matching public port automatically, using UPnP or NAT-PMP. Set this to false on networks where your network team manages port forwarding. Valid options are true or false. The default is true. |
direct_transfer_public_ports | The public ports clients connect to when your firewall presents different port numbers than the ports the Agent listens on. Entries are ports or ranges, in preference order, up to 16 ports in total. Leave this empty when the public and local port numbers match. The default is []. |
direct_transfer_advertised_addrs | Additional public addresses to offer clients, as ip:port entries, for an Agent behind a static public IP address, a port forward, or a load balancer. Host names are not accepted. The default is []. |
direct_transfer_rollover_grace_period | The number of seconds the Agent keeps its previous listener open for in-progress transfers while it updates itself. Set this to 0 to release the listener as soon as active transfers finish. The default is 30. |
direct_transfer_max_total_concurrent_requests | The maximum number of direct transfer requests the Agent handles at one time across all clients. The default is 2048. |
direct_transfer_max_concurrent_requests | The maximum number of direct transfer requests the Agent handles at one time from a single client address. The default is 256. |
direct_transfer_max_requests_per_minute | The maximum number of direct transfer requests the Agent accepts per minute from a single client address. The default is 4096. |
direct_transfer_blocked_client_ips | Client addresses and ranges, such as ["198.51.100.0/24"], that can never connect for direct transfers. Blocked addresses take precedence over allowed ones, so an address that appears on both lists is blocked. The default is []. |
direct_transfer_allowed_client_ips | The client addresses and ranges allowed to connect for direct transfers. When the list is empty, every client not blocked is allowed. When the list is set, only listed addresses can connect. The Agent allows Files.com's own addresses automatically, so list only your client ranges. The default is []. |
High Availability
These settings identify and prioritize this installation when multiple Agent nodes serve one Remote Server.
| Field | Description |
|---|---|
node_name | A name for this Agent installation, shown with the node's status information. Helpful for telling nodes apart when several serve the same Remote Server. Unset by default. |
availability_role | This installation's priority when multiple nodes serve one Remote Server. Valid options are auto, primary, and standby. Files.com sends new work to a reachable primary node first, then to auto nodes, then to standby nodes. The default is auto. |
DNS
The auto setting tries public DNS first and falls back to the local system's DNS resolver if public DNS is unreachable. This works for most deployments. Use doh (DNS over HTTPS via Cloudflare) if your environment requires encrypted DNS lookups or if local DNS returns incorrect results for public hostnames. Use system to rely only on the host's configured DNS resolver when your network routes all DNS through an internal resolver and you do not want the Agent reaching out to public DNS services.
| Field | Description |
|---|---|
dns | The DNS lookup method the Agent uses. Valid options are auto, doh, and system. The default is auto. |
dns_server | A custom DNS server address, as host or host:port (port defaults to 53). Applied whenever the Agent uses the operating system resolver: when dns is set to system, or when dns is auto and the Agent falls back from DNS over HTTPS. Has no effect when dns is set to doh. |
Outbound Proxy
When the Agent runs inside a locked-down network that prohibits direct connections to internet services, you can route all Agent connections through Files.com instead.
| Field | Description |
|---|---|
proxy_all_outbound | Whether to proxy Agent connections through Files.com. Valid options are true or false. |
Integrations
The integrations setting enables the Agent to act as a secure proxy for Remote Server connections. When set, the Agent routes connections from your Files.com site to the integration types you specify.
| Field | Description |
|---|---|
integrations | The integration routing types the Agent supports. Valid options are an empty array [] or one or more of the supported integration routing types. The default is []. |
Logging
These settings control where the Agent writes logs, how much detail it captures, and how it manages log file size. The info level works for most deployments. Use debug only for troubleshooting, as it produces significantly larger log files.
| Field | Description |
|---|---|
log_file | The path and filename for the Agent log. When blank, the Agent writes to the default log location. |
log_level | The level of detail in the Agent log. Valid options are debug, info, warn, error, and fatal. Each level includes all more severe levels. The default is info. |
log_rotate_num | The number of log files to retain. The default is 5. |
log_rotate_size | The size in MB at which the Agent rotates the log file. The default is 50. Setting this to 0 applies the default value. |
disable_remote_log_access | Whether to prevent Files.com from accessing the Agent's log file remotely. Valid options are true or false. The default is false. |
Transfer Rate Limiting
By default, the Agent transfers files at the maximum speed the network allows. On low-bandwidth networks, or where you need to prevent the Agent from saturating available bandwidth, set a rate limit.
| Field | Description |
|---|---|
transfer_rate_limit | The upload and download rate limit for the Agent. The default is no limit. |
Upload Cache
When the Agent uploads files using parallel parts (the default), it buffers each completed part in a local cache before finalizing the transfer. These settings control where that cache is written and whether parallel part uploads are enabled. See Agent Storage Requirements for sizing and storage location guidance.
| Field | Description |
|---|---|
upload_temp_file_part_path | The directory where the Agent stores temporary upload part files. Must be an absolute path on the same filesystem volume as root. When not set, the Agent uses the OS default temporary file location, which may be on a different volume than root. |
upload_parallel_parts | Whether the Agent uploads file parts in parallel. Parallel uploads improve throughput but require the upload cache to be on the same filesystem volume as root. Valid options are true or false. The default is true. |
transfer_cache_size | The maximum number of concurrent upload and download transfer cache entries the Agent holds at one time. This is an entry count, not a size in bytes. The default is 2048. |
Graceful Shutdown
When the Agent shuts down, this setting controls how long it waits for in-progress jobs to complete before stopping. Increasing this value reduces the chance of interrupted transfers when restarting or stopping the Agent.
| Field | Description |
|---|---|
graceful_shutdown_timeout | The number of seconds the Agent waits for in-progress jobs to finish before shutting down. The default is 15. Setting this to 0 applies the default value. |
Read-Only Settings
The following fields are generated by Files.com when the Agent is created and must not be edited. Changing these values prevents the Agent from connecting to your site.
| Field | Description |
|---|---|
id | The unique Remote Server ID for this Agent. Do not edit. |
private_key | The private key that authenticates this Agent to your Files.com site. This is a sensitive credential and must never be shared. Do not edit. |
subdomain | The custom subdomain of the Files.com site this Agent is associated with. Do not edit. |
endpoint_override | The domain name the Agent uses to connect to your site when you have a Custom Domain configured. Do not edit. |