Skip to main content

Moving an Agent to a New Host

When replacing the machine that runs an Agent, install the Agent on the new host using a copy of the existing host's active configuration file. This keeps the same Remote Server connection in Files.com, so existing Mounts, Syncs, and Automations can continue using it after the move. You do not need to create a new Remote Server.

Copying the configuration does not move the files the Agent exposes. The new host must reach the same data, with the same folder layout relative to the Agent's root, so existing remote paths continue to identify the intended files.

Preparing the Configuration and Storage

Locate the active configuration file on the existing host and copy it securely to the new host before uninstalling anything. Use this file instead of downloading a fresh configuration from Files.com: the active file includes changes made locally, such as logging settings and approved Agent Compute commands. Protect it as you would a password because it contains the Agent's credentials.

Keep the connection's id, private_key, subdomain, and endpoint_override values unchanged. Review every configured path for the new machine:

  • The root folder and any linked storage locations must expose the same data and relative folder layout. The host path can differ; update it in the copied configuration if necessary. A matching path that points to an empty folder or different data is not sufficient.
  • If private_key_path references a separate key file, copy that file too. Make sure the path resolves from the configuration file's active location on the new host.
  • Configured log and upload-cache locations must be available and writable by the new service account. Preserve the upload cache's storage requirements.
  • If you use Agent Compute, install the configured programs and scripts and check their paths, working directories, and access to the data they process.

Prepare the new host's network connectivity and service account permissions. Network shares must be accessible to the account running the service, independently of an administrator's signed-in session. On Windows, use UNC paths for network storage.

If you use Direct Transfers or route connections through the Agent, carry over the required network access and update host-specific addresses or port forwarding.

Switching Hosts

Plan the switch for a period when the Agent's work can be interrupted. For a host replacement, stop and uninstall the existing service before starting the service on the new host. Uninstalling prevents the retired host from restarting the Agent and serving work again.

  1. Stop the Agent service on the old host, then uninstall it using the instructions for its installation method. From a shell with permission to manage the service, run files-agent service stop followed by files-agent service uninstall; use files-agent.exe on Windows. For an MSI installation, stop the service in Windows Services, then remove the Agent through Add or remove programs.
  2. If the data resides on the old machine, complete its transfer to the new storage before starting the new Agent. Coordinate other applications that write to that data so the replacement exposes the current files. If the data stays on a network share, make that same share available from the new host.
  3. Follow the operating-system instructions for installing the Agent, using the copied configuration in place of a fresh download. Skip creating a Remote Server. For a Windows MSI installation, place the copied files_agent_config.toml beside the MSI before running it. The MSI starts the service during installation, so run it only after removing the old service. For a command-line installation, select the copied file with --config, then start the new service.

Verifying the Move

Open the existing Agent Remote Server in Files.com and confirm that it shows Connected with the new host's information and the expected root and permissions. Follow the installation verification to check the service and upload cache.

Use the existing Mounts, Syncs, or Automations to test the file operations your workflow needs, using sample files. Confirm that they reach the intended data on the replacement host. A connected Agent alone does not establish that the new service account can access every required folder or perform every required operation.