Edge agent — install & unattended setup

Pre-release

The edge agent is in development (M2). This page documents the intended install flow; packaged downloads arrive with the beta.

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)

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

Install

1. Unzip the agent into a folder, e.g. C:\TenkeyBridge\.

2. Edit appsettings.json:

   {
     "GatewayUrl": "wss://api.tenkeybridge.com/agent",
     "AgentToken": "<your agent token>",
     "CompanyFile": "C:\\Company\\yourfile.qbw"
   }

   Leave CompanyFile empty to use whatever company file QuickBooks has open — set it explicitly for unattended use.

   Optional: ShutdownDrainSeconds (default 10) sets how long a Ctrl-C waits for an in-flight QuickBooks request to finish before exiting. Press Ctrl-C a second time to force-quit immediately.

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

Every key can also be set as an environment variable prefixed with TENKEYBRIDGE_ (e.g. TENKEYBRIDGE_AGENTTOKEN); environment variables override appsettings.json. For unattended setups we recommend setting AgentToken via the environment variable so the token doesn't sit in a config file.

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

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. The agent started at logon: press Win+R, run shell:startup, and drop a shortcut to tenkeybridge-agent.exe there.
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.

Durable logs for unattended installs

Set LogFile (in appsettings.json, or TENKEYBRIDGE_LOGFILE) to a path and 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.

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

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