Skip to main content
When you deploy into highly restricted, secure networks, such as banks, hospitals, factories, or government agencies, your customer’s security team reviews every piece of software before it runs. They check who published the binary, who signed the installer, and where it connects to. A third-party agent with someone else’s name on it can slow that review down or stop it entirely. Fleet Connector is a reference implementation, built on the ngrok Go SDK, that you rename and sign as your own. Your customers see your software, from your publisher name to the service on their machines, while ngrok handles the connectivity underneath. You control:
  • The binary and service name, so the process on the customer’s machine carries your brand.
  • The signature, so Windows shows your company as the publisher instead of ngrok.
  • The installer, so you can ship an MSI or Linux package that fits your customers’ deployment tools.
  • The update channel, so new builds come from your own server, signed by you.
If you don’t need your own brand or signature, run the standard ngrok agent as a background service instead. It’s already signed by ngrok.

What you’ll need

  • An ngrok account. If you don’t have one, sign up.
  • An authtoken for each install.
  • Go on your build machine.
  • For Windows, the .NET SDK 6 or later on your build machine, to install WiX.
  • For Windows, a code-signing certificate from a trusted certificate authority (CA), or a self-signed certificate for testing.
1

Fork the repository

Fork the Fleet Connector repository before you change anything. Your service name, branding, and signing certificate live in your fork, not in the original.
2

Build your release

Build once on your own build machine, not on every install. The output is the installer you distribute to your customers.
Build the binary and an MSI installer with WiX v5:
Setting GOARCH to amd64 builds for standard Intel and AMD PCs, even if you build on an ARM machine. The installer also works on ARM PCs running Windows 11.Then sign the MSI. Fleet Connector is built from source, so it doesn’t carry ngrok’s signature. If you skip this step, the MSI is unsigned: Windows SmartScreen warns about an unknown publisher, antivirus tools may flag it, and you can’t turn on remote updates.
Sign the installers you ship to customers with a code-signing certificate from a trusted CA.
Save the thumbprint from the last command. You need it to turn on remote updates.Replace Your Company with the name on your certificate. The timestamp keeps the signature valid after your certificate expires. If your certificate’s key is on a hardware token or a cloud signing service, sign with the tool your CA provides instead, such as signtool.exe.
3

Configure the agent

Fleet Connector reads its settings from a config.yaml file:
  • Windows: C:\ProgramData\FleetConnector\config.yaml
  • Linux: /etc/fleetconnect/config.yaml
You can create this file in three ways, depending on who installs it and when:
  • gen-config: Generate a config file for each install on your build machine, then pass it to the installer. Whoever runs the install needs only the installer and that file, with no setup on the target machine.
  • Setup wizard: Install without a config file, and the service opens a web form on 127.0.0.1. The form walks a person through setup once, then shuts down after it writes a valid config.
  • Hand-edit: After you install, edit config.yaml directly, or run fleetconnect edit-config to edit it in $EDITOR with validation before it saves. Restart the service to apply your changes.

gen-config

This command generates a config for a private endpoint at https://store-042.ngrok.direct that forwards to localhost:8080. Only your own ngrok account can reach the endpoint. On Windows, it also turns on remote updates.Run it on your build machine, from the folder where you built Fleet Connector. --path names the output file, so you can generate one for each install.
On Windows, it writes the following store-042.yaml. The Linux file is the same without the update_source_url and update_signer_thumbprint lines.
4

Install the service

Install the package on each target machine, and pass it the config file you generated with FLEETCONNECT_INSTALL_CONFIG. Use the file’s full path.
Run in PowerShell as Administrator:
--% stops PowerShell from changing the quotes, so paths with spaces work.
The installer checks the file, puts it at the service’s config path, and starts Fleet Connector as a background service that also starts on every boot. The service connects right away. If the file is invalid, the install fails.To use the setup wizard instead, leave out FLEETCONNECT_INSTALL_CONFIG.
5

Operate the service

Check, stop, and start the service, and follow its logs:

Remote updates

On Windows, you can push a new build to your fleet without touching each machine. To turn on remote updates, set both of these fields in config.yaml:
  • update_source_url: Where the agent downloads a new signed MSI from.
  • update_signer_thumbprint: The thumbprint of the certificate that must have signed it.
When you send an update from the ngrok dashboard or API, the agent receives it over its existing connection. It downloads the MSI and checks the signature against the pinned thumbprint before installing it.

What’s next