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.

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`.

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 512.

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.

Agent Configuration File