Edge agent — install & setup

Production path

The edge agent is the production path for Desktop company files. Credentials and the agent token are issued during onboarding (see Authentication); the signed installer is delivered with your onboarding package until self-serve downloads ship.

The TenkeyBridge edge agent is a small Windows program that sits next to your QuickBooks Desktop or Enterprise install. It makes one outbound, encrypted WebSocket connection to the TenkeyBridge gateway and executes the requests your QBO-style API calls translate into. Nothing on your machine listens for inbound connections.

Requirements

• Windows 10/11 or Windows Server, 64-bit
• QuickBooks Desktop or Enterprise 2023 R16 or later (Enterprise 24 recommended)
• A Windows user session that can stay logged in (see Unattended operation)
• No admin rights needed — the installer is per-user.

The agent is self-contained — no .NET install, no QuickBooks SDK install. The COM interface it uses ships with QuickBooks itself.

Install (recommended)

1. Download TenkeyBridge-Agent-<version>-win-x64.msi from your onboarding package.

2. Double-click it. It installs for your Windows user only — no admin prompt, no UAC. It goes to %LOCALAPPDATA%\Programs\TenkeyBridge\, adds that folder to your PATH, and adds a TenkeyBridge Agent Setup entry to the Start menu.

3. Open a new terminal and run:

   tenkeybridge-agent setup

   It asks for your agent token, the company file path (optional), and whether to start the agent when you sign in, then offers to run the QuickBooks authorization. That's it. The Start menu also has a TenkeyBridge Agent Setup entry that opens the same command as a convenience — but it's a console program, so the window it opens closes as soon as setup finishes, taking any error or summary text with it. Prefer running it from a terminal so you can actually read the output.

Re-run any time

setup is safe to re-run; it shows current values as defaults and keeps anything else already in appsettings.json. tenkeybridge-agent setup --show prints the current configuration with the token masked.

setup options (scripted / silent)

All of setup's prompts have a matching flag, so it can run unattended end to end:

Flag	What it does
--token <token>	Agent token from your TenkeyBridge onboarding
--company-file <path>	Full path to the .qbw file. On a re-run, omitting this flag keeps whatever is already configured; pass --company-file="" (empty) to clear it back to using whatever QuickBooks has open
--gateway-url <url>	Gateway WebSocket URL (default wss://api.tenkeybridge.com/agent) — only asked for interactively with --advanced
--advanced	Also ask for the gateway URL interactively
--startup on|off	Create or remove the sign-in Startup shortcut (default: ask)
--grant	Run the QuickBooks authorization (same as tenkeybridge-agent grant)
--yes, -y	Accept defaults, ask nothing (Startup shortcut ends up on unless --startup off is also given; the grant only runs if --grant is also given)
--show	Print the current configuration (token masked) and exit

setup exits 0 on success. It exits 2 when a value you passed is invalid (--company-file must exist and end in .qbw; --gateway-url must be ws:// or wss://), when a required value is missing and there's no terminal to ask on (for example a scripted run with no --token and no existing appsettings.json), or when the existing appsettings.json isn't valid JSON. setup --show exits 1 if the agent hasn't been configured yet.

Fully unattended example:

tenkeybridge-agent setup --token tkba_exampleToken123 --company-file "C:\Company\ExampleCo.qbw" --startup on --yes

What the installer does / where things live

Path	Owned by	Notes
%LOCALAPPDATA%\Programs\TenkeyBridge\tenkeybridge-agent.exe	Installer	The agent binary
%LOCALAPPDATA%\Programs\TenkeyBridge\appsettings.example.json	Installer	Reference config; not read by the agent
%LOCALAPPDATA%\Programs\TenkeyBridge\appsettings.json	setup	Created/updated by setup; install, upgrade, and uninstall never touch it
%LOCALAPPDATA%\Programs\TenkeyBridge\agent.log	the agent	setup only writes this path into appsettings.json; the file itself is created the first time the agent (or grant) actually runs. Never touched by install, upgrade, or uninstall
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\TenkeyBridge Agent.lnk	setup	The sign-in Startup shortcut, created when you answer Yes (or pass --startup on)
Start menu → TenkeyBridge Agent Setup	Installer	Runs tenkeybridge-agent.exe setup
PATH (HKCU\Environment)	Installer	So tenkeybridge-agent works from any terminal

Uninstalling (Settings → Apps → TenkeyBridge Agent) removes the program files, the Start-menu shortcut, the sign-in Startup shortcut (if present), and the PATH entry only. Your appsettings.json and agent.log are left in place, so reinstalling picks your configuration back up without re-running setup.

Verifying the download

Windows shows the publisher name when you run the MSI. Empire Innovations, LLC is the genuine signer. Until the trusted certificate ships, builds are signed with a development certificate instead — Windows will show an "unknown publisher" warning (and SmartScreen may flag it) even though the file is legitimate. You'll receive a build signed with the trusted certificate through your onboarding package once that lands; there's nothing to do differently in the meantime beyond expecting the warning.

A SHA256SUMS file ships alongside the installer and the exe. To confirm your download matches, run in PowerShell:

Get-FileHash .\TenkeyBridge-Agent-<version>-win-x64.msi -Algorithm SHA256

and compare the hash against the matching line in SHA256SUMS.

Silent / scripted install

msiexec /i TenkeyBridge-Agent-<version>-win-x64.msi /qn

then run setup with flags, as in the example above. To upgrade, install the newer MSI over the old one — the per-user MajorUpgrade rule handles removing the previous version.

winget validate-ready manifests live in the repo (apps/agent/installer/winget/); a winget community listing (so winget install Empire.TenkeyBridgeAgent works without a direct download link) is planned but not live yet. The checked-in manifests carry a placeholder InstallerUrl and an all-zero InstallerSha256 — they can't be submitted to the community repo until a real, public MSI download exists to point at.

Configuration reference

Key	Required	Default	What it does
GatewayUrl	Yes	—	WebSocket URL of the TenkeyBridge gateway
AgentToken	Yes	—	Token that authenticates this agent to the gateway
AgentId	No	machine name	Identifier for this agent, sent to the gateway in the hello frame
CompanyFile	No	empty	Full path to the .qbw company file; empty uses whatever file QuickBooks has open — set it explicitly for unattended use
AppName	No	TenkeyBridge Agent	Application name passed to QuickBooks (OpenConnection2); this is the name QuickBooks shows in the integrated-application grant
ShutdownDrainSeconds	No	10	How long Ctrl-C waits for an in-flight request to finish before exiting
LogFile	No	empty	Path to a log file written directly with autoflush (in addition to the console). Durable for unattended installs; empty = console only. setup sets this to agent.log beside the exe unless you've already set it

Every key can also be set as an environment variable prefixed with TENKEYBRIDGE_ (e.g. TENKEYBRIDGE_AGENTTOKEN); environment variables override appsettings.json. setup requires a token and always writes the one you give it into appsettings.json — there's no flag to skip that. If you'd rather the token not sit in the config file, hand-write appsettings.json from the Configuration reference without an AgentToken key (or run setup once and then delete the key afterwards), and set TENKEYBRIDGE_AGENTTOKEN in the environment of the session that runs the agent — environment variables always win.

Authorize the agent in QuickBooks (one time)

1. Open QuickBooks as Admin, with your company file open.
2. Run tenkeybridge-agent.exe grant from the agent folder — or answer Yes when setup asks "Authorize in QuickBooks now?", or pass setup --grant to do it non-interactively as part of a scripted setup.
3. QuickBooks shows its integrated-application dialog. Choose "Yes, always; allow access even if QuickBooks is not running" and select the user the agent should log in as.
4. The command prints QuickBooks' host information and exits 0. Done.

This grant is stored per company file by QuickBooks (Edit → Preferences → Integrated Applications), where you can revoke it at any time.

QuickBooks identifies an application partly by its code-signing certificate, so moving from an unsigned build to a signed one (or between signing certificates) makes it prompt once more. Grant it again the same way.

Run QuickBooks and the agent at the same Windows privilege level

QuickBooks' COM interface only lets the agent attach when both processes run at the same Windows integrity level. If QuickBooks is running elevated (as Administrator) but the agent is not, the connection silently fails — QuickBooks tries to launch a second instance and you get QB_CONNECTION_ERROR — Could not start QuickBooks, which looks identical to other connection problems.

The simple rule: do not run QuickBooks as Administrator. Launch it normally (non-elevated) and run the agent normally too — they then match automatically. This is also Intuit's own recommendation. In the unattended setup below, the agent opens its own QuickBooks session, so the levels always match.

Unattended operation

QuickBooks' automation interface cannot run from a Windows service. The supported pattern is:

1. A dedicated Windows user set to log on automatically at boot.
2. Run tenkeybridge-agent setup --startup on (or just answer Yes when setup asks) so the agent starts at sign-in. This replaces the old approach of hand-dropping a shortcut into shell:startup — setup creates that shortcut for you.
3. QuickBooks stays closed; the agent opens its own session with the company file using the grant above.

The machine can be locked; the session must stay logged in.

Running on a terminal server / hosted QuickBooks with several users and multi-user company files? See Hosted & multi-user QuickBooks.

Durable logs for unattended installs

setup already sets LogFile to agent.log beside the exe, so the agent writes every log line straight to that file with autoflush — independent of stdout, so it survives a redirected console and is not lost if the process is force-killed. Tail it live with Get-Content -Wait <path>. Prefer this over redirecting stdout to a file.

Manual install (hosted / RDS admins)

Some setups — hosted QuickBooks, RDS terminal servers, one Windows session per company file — call for installing without the per-user MSI's PATH/Start-menu integration, or for installing several independent copies on one machine. For those, use the single-file exe tenkeybridge-agent-<version>-win-x64.exe, also included in your onboarding package:

1. Put it in a folder you own, e.g. C:\TenkeyBridge\.
2. Run tenkeybridge-agent.exe setup from that folder — it writes appsettings.json next to the exe, exactly like the MSI path does.
3. Alternatively, skip setup and hand-write appsettings.json yourself from the Configuration reference above.

The QuickBooks authorization step is the same either way — see Authorize the agent in QuickBooks above.

For the full pattern of one Windows session per company file, scheduled-task autostart, and integrity-level notes specific to shared servers, see Hosted & multi-user QuickBooks.

Troubleshooting

Error code	Meaning	Fix
COM_UNAVAILABLE	QuickBooks Desktop isn't installed on this machine	Install QuickBooks on the machine the agent runs on
QB_CONNECTION_ERROR	QuickBooks refused the connection or session	Re-run the grant; check the company file path; make sure QuickBooks isn't open with a different company file
QB_REQUEST_ERROR	A request failed twice against a fresh session	Check QuickBooks is healthy; the agent log has the underlying message
setup says company file not found	The path doesn't exist, or doesn't end in .qbw	Check the path in QuickBooks: File → Open Previous Company shows the file it last had open; the file must end in .qbw
The agent process disappears the moment a request reaches QuickBooks (Event Viewer logs 0xc0000409 / BEX64 against tenkeybridge-agent.exe)	The exe's code-signing certificate does not chain to a root this machine trusts — QuickBooks validates the caller's chain before opening a session	Run Get-AuthenticodeSignature .\tenkeybridge-agent.exe; if Status isn't Valid, reinstall from the official signed download. Only self-built or internally re-signed agents hit this

The agent reconnects to the gateway automatically with backoff — a dropped internet connection heals on its own.