Hosted & multi-user QuickBooks (RDS / terminal server)

Not currently offered

The Windows edge agent is not part of the public product today. Connect QuickBooks with the built-in Web Connector instead — nothing to install; on Rightworks or another hosted desktop, follow the Rightworks guide. This page is kept for existing agent users and for reference; contact hello@tenkeybridge.com if you need it. On Rightworks specifically, the agent is an opt-in second path installed by Rightworks support — read The agent option before anything below.

This page covers running the edge agent where QuickBooks is hosted — a Windows Server with Remote Desktop Services (terminal server), an application hosting provider, or any box where several people are logged in at once and the company file is open in multi-user mode. Read Edge agent install first; everything there still applies (hosted admins usually use the manual install — one exe per user session). This page only adds what changes when the machine is shared.

Validated configuration

Windows Server 2022 with the RDS Session Host role, QuickBooks Enterprise 24 as the database server and client, three company files hosted in multi-user mode, two users logged in over RDP with different files open, the agent running as a standard (non-admin) user — verified end-to-end (reads, creates, and sparse updates) on 2026-08-15. Requires an agent build from that date or later.

The one rule: the agent lives in a user's session

QuickBooks' automation interface (COM) is per Windows session. An agent can only talk to a QuickBooks instance running in the same logged-in session as itself — it cannot see, and is not affected by, QuickBooks windows other users have open in their own sessions.

That gives you a simple model:

You want	Do this
The API to reach one company file	Log one user in (say qbagent), open — or let the agent open — that file in that session, run one agent there
The API to reach several company files on the same server	One Windows session per company file, each with its own agent, its own agent token, and its own company
Other staff to keep using QuickBooks interactively	Nothing special — their sessions are independent of the agent's

Everything the agent needs is in that session; it does not require the QuickBooks database server manager to be running in its session (that service runs in session 0 and serves everyone).

Multi-user mode

Company files hosted in multi-user mode work as-is. The agent opens its session in "don't care" mode, so it joins whichever mode the file is currently in — you do not need to switch the file to single-user for the agent, and users can keep working in it while the API reads and writes.

Older agent builds

Agent builds before 2026-08-15 requested a single-user session and failed against a multi-user file with QB_CONNECTION_ERROR — The QuickBooks company data file is currently open in a mode other than the one specified by your application. Update the agent if you see that message on a hosted server.

Setting it up on a shared server

For each company file you want on the API:

1. Create (or pick) a Windows user for that file, e.g. qbagent-exampleco. A standard user is fine — the agent needs no admin rights. Add it to Remote Desktop Users if you'll set it up over RDP.

2. Log that user in (RDP is fine) and put the single-file tenkeybridge-agent-<version>-win-x64.exe in a folder the user owns, e.g. C:\Users\qbagent-exampleco\TenkeyBridge\.

3. Configure — set CompanyFile to that user's file so the agent attaches to the right one even before anyone opens it. The fastest way is one command in that session:

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

   That's equivalent to writing appsettings.json by hand:

   {
     "GatewayUrl": "wss://api.tenkeybridge.com/agent",
     "CompanyFile": "C:\\QBCompanyFiles\\ExampleCo.qbw",
     "LogFile": "C:\\Users\\qbagent-exampleco\\TenkeyBridge\\agent.log"
   }

   setup always writes the token you give it into appsettings.json. If you'd rather it not sit in the file at all — a shared server means other users may be able to read your folder — hand-write appsettings.json without an AgentToken key and set TENKEYBRIDGE_AGENTTOKEN in the environment instead; the environment variable overrides the file either way.

4. Grant access once, in that session, with the file open in QuickBooks: tenkeybridge-agent.exe grant → "Yes, always; allow access even if QuickBooks is not running".

5. Start the agent at logon — either the per-user Startup folder (Win+R → shell:startup → shortcut to the exe), or a logon-triggered scheduled task, which survives the user closing the console window:

   # run in that user's session (non-elevated); prompts for the user's password
   schtasks /Create /TN tkb-agent /TR "C:\Users\qbagent-exampleco\TenkeyBridge\run-agent.cmd" `
     /SC ONLOGON /RU qbagent-exampleco /IT /RL LIMITED

   /IT (interactive) and /RL LIMITED (not elevated) are what make the task land in the user's desktop session at the same privilege level as QuickBooks — both are required for COM to attach.

6. Keep that user logged in (disconnected is fine — do not sign out). Set the RDS session limits so idle/disconnected sessions for the agent user are never ended.

Repeat per company file with a different user, token, and company.

Integrity levels on a terminal server

The same-privilege rule from the install guide holds: QuickBooks and the agent in a given session must both be elevated or both not. On RDS this is easy — users are normally standard users, nothing runs elevated, and the levels match by default. Only the QuickBooks instance in the agent's own session matters; an administrator running QuickBooks elevated in another session does not affect your agent.

Older agent builds

Before 2026-08-15 the agent's integrity check looked at every QBW.exe on the machine and could report QB_INTEGRITY_MISMATCH — QuickBooks (QBW.exe, PID …) is running elevated because of another user's QuickBooks. Update the agent if you see that on a shared server.

Application hosting providers

If your QuickBooks is hosted by a provider (you RDP into their server), the same model applies. Whether you can run the agent yourself depends on the provider:

• Providers that let you run your own programs (a Windows Server you RDP into): no installer, no admin rights, no SDK — unzip and run in your own session, as above.
• Rightworks does not let you run an .exe yourself. Their support installs the program for you (reportedly Deluxe plan only), and it lives and dies with your session's 2-hour idle logoff. See The agent option for the honest picture, the support-chat message to send, and why Web Connector remains the default there.
• Company files typically live on a UNC or mapped path the provider gives you (e.g. Q:\ExampleCo.qbw); use that as CompanyFile.
• If scheduled tasks are locked down, the Startup-folder shortcut works.
• Your session must stay logged in; ask the provider about idle-logoff policies for a dedicated automation user.

Sessions that come and go

A hosted session isn't always-on: it can be disconnected (the agent's Windows session survives, if the host allows it), logged off at an idle limit (the agent exits), or moved to another server behind a load balancer (the network path changes). The agent is built for that:

• It reconnects with jittered exponential backoff (1 s growing to a 60 s cap), and a network change or session reconnect skips the wait and reconnects straight away.
• A dead connection that never closes (no FIN/RST) is detected by WebSocket keep-alive (a ping every 30 s, abandoned after 90 s without an answer) and replaced.
• On logoff or shutdown it closes the connection cleanly, so TenkeyBridge marks the company offline at once and callers get a fast 503 AGENT_OFFLINE rather than waiting on a timeout.
• If QuickBooks isn't open in the agent's session it reports QB_NOT_OPEN (a 503; nothing was sent, so retry freely). By default the agent still tries to launch QuickBooks on demand; set RequireQuickBooksRunning to true to make it fail fast instead — see the configuration reference.
• Once a day it asks TenkeyBridge whether a newer version exists and logs a line if so. It never updates itself.

Troubleshooting on shared servers

Symptom	Likely cause	Fix
QB_CONNECTION_ERROR … open in a mode other than the one specified	Agent build older than 2026-08-15 against a multi-user file	Update the agent
QB_INTEGRITY_MISMATCH naming a PID that isn't your QuickBooks	Agent build older than 2026-08-15	Update the agent
Agent connects to the gateway but every request is QB_CONNECTION_ERROR	Agent is not in the same session as the QuickBooks it should use, or was started by a service / bare SSH shell (session 0)	Start it from the user's interactive session (Startup folder or schtasks … /IT /RL LIMITED)
Requests return 503 QB_NOT_OPEN	QuickBooks isn't running in the agent's own Windows session (closed, or the session was reconnected without it)	Open QuickBooks on the pinned file in that session and retry — nothing was executed
Requests hit the wrong company file	CompanyFile empty and the user has a different file open	Set CompanyFile explicitly
Agent stops after the user's RDP window is closed	The user signed out instead of disconnecting, or an RDS policy ended the session	Disconnect only; exempt the agent user from session-end policies

The gateway's error reference has the full list of codes.