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

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

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 and you usually don't need the provider's help:

• No installer, no admin rights, no SDK — unzip and run in your own session.
• 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.

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