> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ship a Custom-Branded Agent with Fleet Connector

> Learn how to build, sign, and install your own branded ngrok agent as a background service on Windows and Linux with Fleet Connector.

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](https://ngrok.com/docs/agent-sdks.md), 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](https://ngrok.com/docs/gateway/site-to-site-connectivity/background-service.md) instead.
It's already signed by ngrok.

## What you'll need

* An ngrok account.
  If you don't have one, [sign up](https://dashboard.ngrok.com/signup).
* An [authtoken](https://dashboard.ngrok.com/authtokens) for each install.
* [Go](https://go.dev/dl/) on your build machine.
* For Windows, the [.NET SDK](https://dotnet.microsoft.com/download) 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](https://github.com/ngrok-adhoc/fleet-connector/fork) 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.

> [tab] Windows
>
> Build the binary and an MSI installer with [WiX v5](https://wixtoolset.org/):
>
> ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> git clone https://github.com/<your-account>/<your-fork>.git
> cd <your-fork>
> $env:GOARCH = "amd64"
> go build -o fleetconnect.exe .\cmd\fleetconnect
>
> dotnet tool install --global wix --version "5.*"
> wix extension add WixToolset.Util.wixext/5.0.2
> wix build installer\product.wxs `
>   -ext WixToolset.Util.wixext/5.0.2 -arch x64 `
>   -d FleetConnectExeSource=fleetconnect.exe `
>   -out FleetConnector.msi
> ```
>
> 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.
>
> > [tab] CA certificate
> >
> > Sign the installers you ship to customers with a code-signing certificate from a trusted CA.
> >
> > ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> > $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert |
> >   Where-Object Subject -like "CN=Your Company*" |
> >   Select-Object -First 1
> >
> > Set-AuthenticodeSignature -FilePath FleetConnector.msi `
> >   -Certificate $cert -HashAlgorithm SHA256 `
> >   -TimestampServer "http://timestamp.digicert.com"
> >
> > (Get-AuthenticodeSignature FleetConnector.msi).SignerCertificate.Thumbprint
> > ```
> >
> > 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`.
>
> > [tab] Self-signed certificate
> >
> > Use a self-signed certificate to test your build.
> > Windows doesn't trust it on other machines, so don't ship installers signed with it.
> >
> > ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> > $cert = New-SelfSignedCertificate -Type CodeSigningCert `
> >   -CertStoreLocation Cert:\CurrentUser\My -Subject "CN=Your Company"
> >
> > Set-AuthenticodeSignature -FilePath FleetConnector.msi `
> >   -Certificate $cert -HashAlgorithm SHA256
> >
> > (Get-AuthenticodeSignature FleetConnector.msi).SignerCertificate.Thumbprint
> > ```
> >
> > Save the thumbprint from the last command.
> > You need it to turn on remote updates.
> >
> > To test remote updates, trust the certificate on each machine you install on.
> > Remote updates only install an MSI with a valid signature.
> >
> > ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> > $cert | Export-Certificate -FilePath test-signing.cer
> > Import-Certificate -FilePath test-signing.cer `
> >   -CertStoreLocation Cert:\LocalMachine\Root
> > ```

> [tab] Linux
>
> Build the binary and a `.deb` package with [nFPM](https://nfpm.goreleaser.com/):
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> git clone https://github.com/<your-account>/<your-fork>.git
> cd <your-fork>
> GOOS=linux GOARCH=amd64 go build -o fleetconnect ./cmd/fleetconnect
>
> go install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest
> nfpm package --config installer/linux/nfpm.yaml \
>   --packager deb --target dist/
> ```
>
> To build an `.rpm` package instead, use `--packager rpm`.
> To build for ARM machines, set `GOARCH=arm64` and change `arch` in `installer/linux/nfpm.yaml` to `arm64`.
> Build one package for each architecture you deploy to.

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

> [tab] Windows
>
> ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> .\fleetconnect.exe gen-config `
>   --path store-042.yaml `
>   --description "store-042" `
>   --url https://store-042.ngrok.direct `
>   --binding internal `
>   --upstream localhost:8080 `
>   --authtoken "<your authtoken>" `
>   --update-source-url "https://updates.example.com/latest/fleetconnect.msi" `
>   --update-signer-thumbprint "AABBCCDDEEFF00112233445566778899AABBCCDD"
> ```

> [tab] Linux
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> ./fleetconnect gen-config \
>   --path store-042.yaml \
>   --description "store-042" \
>   --url https://store-042.ngrok.direct \
>   --binding internal \
>   --upstream localhost:8080 \
>   --authtoken "<your authtoken>"
> ```

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.

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
schema_version: 1
description: store-042
credential:
    provider: static
    params:
        authtoken: <your authtoken>
endpoints:
    - url: https://store-042.ngrok.direct
      upstream:
        url: localhost:8080
      bindings:
        - internal
update_source_url: https://updates.example.com/latest/fleetconnect.msi
update_signer_thumbprint: AABBCCDDEEFF00112233445566778899AABBCCDD
```

> [accordion] gen-config flags
>
> | Flag | Description |
> | - | - |
> | `--description` | Human-readable description. Required. |
> | `--url` | Endpoint URL for a single endpoint, such as `https://store-042.ngrok.direct`. |
> | `--upstream` | Local address a single endpoint forwards to, such as `localhost:8080`. |
> | `--binding` | Binding for a single endpoint: `public` (default), `internal`, or `kubernetes`. |
> | `--endpoint` | One endpoint, as `"name=...,upstream.url=...,url=...,bindings=..."`. Repeat for multiple endpoints. Can't be combined with `--url`, `--upstream`, or `--binding`. |
> | `--authtoken` | A literal value, `env:VAR`, or `file:PATH`. |
> | `--path` | Where to write the config. Defaults to `config.yaml` in the current directory. |
> | `--connect-url` | Your [custom connect URL](https://ngrok.com/docs/gateway/site-to-site-connectivity/custom-connect-url.md). |
> | `--connect-ca-cert-file` | PEM CA bundle to trust for `--connect-url`. |
> | `--proxy-url` | Outbound HTTP or SOCKS proxy for the agent's own connection. |
> | `--heartbeat-interval` | Connection heartbeat interval, such as `30s`. |
> | `--heartbeat-tolerance` | How long to tolerate a missed heartbeat, such as `1m`. |
> | `--update-source-url` | Windows only. Leave it blank to turn off remote updates. |
> | `--update-signer-thumbprint` | Required when you set `--update-source-url`. |

> [accordion] config.yaml reference
>
> ```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> schema_version               required, must be 1
> description                  human-readable label (optional)
> metadata                     session metadata visible in the dashboard and API (optional)
> credential:
>   provider                   required, "static" is the only built-in provider
>   params:
>     authtoken                the authtoken the agent connects with
> endpoints:                   one entry per endpoint (optional)
>   - name                     friendly name (optional)
>     url                      endpoint URL; blank = https, or tcp://, tls://
>     upstream:
>       url                    required, local address to forward to
>       protocol               "http1" (default) or "http2"
>       proxy_protocol         "1", "2", or empty
>       tls_verify             verify the upstream's TLS certificate (default: false)
>       tls_verify_cas         PEM CA bundle path; empty = system CA pool
>     bindings                 for example ["public"] or ["internal"] (optional)
>     metadata                 per-endpoint metadata (optional)
>     description              per-endpoint description (optional)
>     traffic_policy           inline Traffic Policy, YAML or JSON string (optional)
>     agent_tls_termination:   (optional)
>       server_certificate     PEM certificate
>       server_private_key     PEM private key
>       mutual_tls_certificate_authorities   PEM CA bundle (optional)
>     pooling_enabled          bool (optional)
> connect_url                  custom connect URL (optional)
> connect_ca_cert_file         PEM CA bundle to trust for connect_url (optional)
> proxy_url                    outbound HTTP or SOCKS proxy for the agent's own connection (optional)
> heartbeat_interval           for example "30s" (optional)
> heartbeat_tolerance          for example "1m" (optional)
> log_level                    debug, info (default), warn, or error
> update_source_url            Windows only; blank turns off remote updates
> update_signer_thumbprint     required when update_source_url is set
> ```

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

> [tab] Windows
>
> Run in PowerShell as Administrator:
>
> ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> msiexec --% /i FleetConnector.msi /quiet FLEETCONNECT_INSTALL_CONFIG="C:\path\to\store-042.yaml"
> ```
>
> `--%` stops PowerShell from changing the quotes, so paths with spaces work.

> [tab] Linux
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> sudo FLEETCONNECT_INSTALL_CONFIG=/path/to/store-042.yaml dpkg -i fleetconnect_*.deb
> ```

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:

> [tab] Windows
>
> ```powershell theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> sc.exe query FleetConnector
> sc.exe stop FleetConnector
> sc.exe start FleetConnector
>
> Get-Content `
>   C:\ProgramData\FleetConnector\logs\fleetconnect.log `
>   -Tail 20 -Wait
> ```

> [tab] Linux
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> systemctl status fleetconnect
> systemctl stop fleetconnect
> systemctl start fleetconnect
>
> journalctl -u fleetconnect -f
> ```

## 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

* [Set up a custom connect URL](https://ngrok.com/docs/gateway/site-to-site-connectivity/custom-connect-url.md) so your agents connect to your own hostname.
* [Get dedicated IPs for your agent connections](https://ngrok.com/docs/gateway/agent/connect-url.md#dedicated-ips) so your customers can allowlist addresses unique to your account.
  [Contact ngrok](https://ngrok.com/contact) to get started.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.