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.

Approved Commands for Agent Compute

The commands setting defines the programs an Agent Compute node can run on this host. It is an array of command definitions, written as one [[commands]] TOML table per command. The downloaded configuration file does not include command definitions. Add them locally; with no definitions, the Agent rejects every Agent Compute command.

Command approval stays on the machine that runs the program so the host administrator controls which local capabilities Automations can use. Permission to edit an Automation does not also grant permission to add executable commands to the Agent. The host administrator chooses which programs and parameters to expose through these definitions.

Each definition gives a command a name. The Automation's Command field must match that name exactly, including capitalization. The executable path and its arguments belong in the definition on the Agent host.

For each parameter supplied by the Automation, add a [[commands.schema]] table immediately after its command definition. Set name to the parameter name and type to its data type. Parameter names must start with an uppercase letter and contain only letters, digits, and underscores, such as InputPath. Use string for a file path or other text; int, bool, and float64 are also supported. An optional default supplies a value when the Automation omits that parameter. Use the same parameter name in the Automation's Arguments and in the Agent's template.

Agent templates use Go template syntax, such as {{.InputPath}}. They are separate from the Automation's TransformScript templates, such as {{ attributes.path }}, which Files.com evaluates before sending the argument value to the Agent.

On Linux or Mac, this example uses /usr/bin/printf to return the supplied path text in standard output:

[[commands]]
name = "report_path"
description = "Return the path supplied by the Automation"
command = "/usr/bin/printf"
arguments = ["%s\n", "{{.InputPath}}"]

[[commands.schema]]
name = "InputPath"
type = "string"

For this example, set the Automation's Command to report_path and add an Arguments entry named InputPath with the value {{ attributes.path }}. The next node receives the path text in payload.stdout.

On Windows, this command requires no parameters and returns the account running the Agent. Select agent_identity in the Automation's Command field and leave Arguments empty:

[[commands]]
name = "agent_identity"
description = "Return the Windows account running the Agent"
command = 'C:\Windows\System32\whoami.exe'
arguments = []

Single-quoted TOML strings preserve the backslashes in Windows paths. The Agent starts the executable directly and passes each arguments entry separately. To run a script, set command to its interpreter and include the script's path and parameters in arguments. The program runs with the operating-system permissions of the account running the Agent, so that account needs access to the executable, scripts, and files they use.

Stop the Agent service before editing its active configuration file, then start it again to load the definitions. Place command tables after the existing top-level settings so those settings remain outside the tables. For Agent High Availability, configure the commands and install their programs on every node that can serve the Remote Server.

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.

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.

Use push_update_block_windows to keep updates from starting during your busy periods.

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.

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.

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.

High Availability

These settings identify and prioritize this installation when multiple Agent nodes serve one Remote Server.

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.

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.

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.

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.

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.

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.

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.

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.