Documentation

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.

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

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. By default, it scales concurrency based on the number of available CPUs multiplied by 4. 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, not just CPU count. 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. When not set, the Agent uses the default of CPUs × 4.

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

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 20. Setting this to 0 applies the default value.

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.

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

Get The File Orchestration Platform Today