File Server Agent: Install & Enrollment
Pairing a Windows machine to a BYOVault tenant for the first time, from running the installer to the agent receiving its own credential.
The installer
The agent ships as a standard Windows Installer (MSI) package, because the agent runs as a real Windows service and MSI’s service-install mechanism is the native way to register one.
The wizard follows the familiar install-directory-picker sequence, with one additional page inserted before the final confirmation step: a page describing the pairing step that is about to run.
There is no field on that page for an API URL or a token — production installs always point at the default API endpoint, and the actual sign-in happens in a separate window launched once installation begins.
Enrollment is mandatory, not an optional post-install step. The installer launches the pairing window as a blocking action partway through installation and waits for it to exit.
If the admin cancels that window, the whole install fails and rolls back rather than completing with an unpaired agent.
msiexec /quiet or /qn) has no one to see the pairing window, so it is skipped automatically. A silent or scripted install must enroll through the separate token-based path described below instead.Pairing during an interactive install
Once the pairing window opens, it requests a one-time pairing code from BYOVault and displays it alongside a link to the portal’s pairing page. This is deliberately treated as a two-device flow.
- The code and link are the primary, always-visible way to proceed.
- An “Open Here” button is offered only as a shortcut, on a machine that happens to have a browser.
- Many real file servers — particularly Windows Server Core — have no browser at all, so an admin normally reads the code or copies the link and completes the next step on a phone or a separate workstation.
The pairing code is a short, easy-to-read code that avoids easily-confused characters, so it can be read aloud or copied by hand without mistakes — the same reasoning behind similar device-pairing codes used elsewhere in the industry. It expires 12 minutes after it is requested.
Signing in on the other device
On the separate device, the admin opens the pairing link (or types the code in manually), signs in with either a Microsoft account or a BYOVault email and password, and is shown which machine is requesting to pair by hostname.
Registering the file server
After signing in, the admin selects which tenant this file server belongs to and gives it a name — pre-filled with the machine’s hostname, but editable. Submitting that step is what actually registers the file server in BYOVault, where it appears as Pending Enrollment.
How the agent learns it has been approved
The pairing window checks the code’s status in the background and receives the agent’s permanent credential once the code has been approved. The portal itself never sees that credential. A code that goes unapproved for too long is retired automatically.
Once the agent receives its credential, the pairing window closes and the install completes. The BYOVaultAgent service starts automatically and begins polling for work on its own schedule — it does not back up anything yet, since no folders have been scoped. The next step is adding one or more paths to the file server’s configuration from the BYOVault dashboard.
Re-enrolling an existing machine
A machine that already has backup history reattaches to it automatically on a normal software reinstall, even though the agent’s stored credential does not survive the reinstall.
If the whole operating system was rebuilt rather than just the agent reinstalled, that automatic reattachment isn’t possible. In that case the installer instead offers an explicit picker of the tenant’s existing file servers, so an admin can confirm by hand which one this machine replaces rather than relying on any automatic guess.
The advanced token-based path
A separate enrollment path is available for these cases: an admin generates a one-time enrollment token from the portal, pastes it into the agent’s enrollment dialog (reached from “Advanced: I have an enrollment token” on the Start Menu enrollment shortcut), and the agent exchanges it directly for its credential in a single call.
This path has its own, separate expiry — the token is valid for 30 minutes from creation — entirely independent of the device-pairing code’s 12-minute lifetime, since the two are unrelated mechanisms.
This is also the path a silent or fully scripted install must use, since the interactive pairing window is skipped in that case.
Once enrolled, see Agent: Updates & Lifecycle for how the agent keeps itself current, and Agent: Bandwidth & Concurrency for how it behaves on the network once real backup jobs start running.