QuickBooks Desktop On-Premise Setup

QuickBooks Desktop runs locally and can’t be accessed directly from the cloud. To sync data from it, you need two things running on your network:

1. CData QuickBooks Desktop Gateway — A Windows service that exposes QuickBooks data over HTTP/HTTPS
2. Resplendent Sync Agent — A Docker container that connects to our cloud and relays sync requests to the Gateway

The sync agent connects outbound to Resplendent (no inbound firewall rules needed). When a sync runs, our cloud tells the agent what to fetch, the agent queries the Gateway, and sends the data back.

┌─────────────────────────────────────────────────────────────────┐
│                      Your local network                         │
│                                                                 │
│  ┌──────────────────┐         ┌──────────────────────────────┐  │
│  │   Linux VM       │  HTTP   │   Windows machine            │  │
│  │   (Sync Agent)   │◄───────►│   (QuickBooks + Gateway)     │  │
│  └────────┬─────────┘         └──────────────────────────────┘  │
│           │                                                     │
└───────────│─────────────────────────────────────────────────────┘
            │ WebSocket (outbound only)
            ▼
    ┌───────────────────┐
    │  Resplendent      │
    │  Cloud            │
    └───────────────────┘

---

Part 1: Create a sync agent in Resplendent

Sync agents are available on Business tier and above. A Staff or Admin user can create and edit an agent.

1. Log in to Resplendent at https://app.resplendentdata.com
2. Go to Settings → Sync Agents in the left sidebar
3. Click Add Sync Agent
4. Enter a name for your agent (e.g., “Office Sync Agent”)
5. Click Save

The dialog shows the Agent UUID immediately. The Agent Key shows Pending save until you save the agent. After saving, keep the dialog open and copy both values—you’ll need them when installing the agent.

If you close the dialog before copying the credentials, click the agent’s name in the table to view them again.

---

Part 2: Install the sync agent

Requirements

• 64-bit x86 Linux server (Ubuntu 22.04+ or similar)
• Docker Engine and Docker Compose v2 installed
• 4 vCPU, 8 GB RAM, and 40 GB of available SSD storage for a production deployment
• Network access to your Windows machine running QuickBooks
• Outbound HTTPS and WebSocket access to app.resplendentdata.com on TCP port 443

For evaluation or light use, the minimum profile is 2 vCPU, 4 GB RAM, and 20 GB of available storage. The agent also runs on Windows with WSL2 or macOS for evaluation, but we recommend a dedicated Linux VM because it is easier to keep running 24/7. See Sync Agent requirements for high-volume sizing and additional guidance.

Quick install

SSH into your server and run:

mkdir resplendent_sync_agent
cd resplendent_sync_agent
curl -sSL https://app.resplendentdata.com/api/public/sync-agent-install.sh | bash

The script prompts for your Agent UUID and Agent Key. It creates a docker-compose.yaml and starts the agent.

Manual install

If you prefer not to pipe scripts to bash, create docker-compose.yaml manually:

name: resplendent-sync-agent

services:
  sync-agent:
    image: resplendentdata/sync-agent:latest
    container_name: sync-agent
    environment:
      - SYNC_AGENT_UUID=your-uuid-here
      - SYNC_AGENT_KEY=your-key-here
      - SYNC_AGENT_UPDATER_URL=http://sync-agent-updater:8080/v1/update
      - SYNC_AGENT_UPDATER_TOKEN=generate-a-long-random-token
    restart: always

  sync-agent-updater:
    image: resplendentdata/sync-agent-updater:latest
    container_name: sync-agent-updater
    group_add:
      - '999'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./docker-compose.yaml:/config/docker-compose.yaml:ro
    environment:
      - SYNC_AGENT_UPDATER_TOKEN=generate-a-long-random-token
      - SYNC_AGENT_COMPOSE_FILE=/config/docker-compose.yaml
      - SYNC_AGENT_COMPOSE_PROJECT=resplendent-sync-agent
      - SYNC_AGENT_SERVICE_NAME=sync-agent
      - SYNC_AGENT_UPDATE_AUTO_THROTTLE_SECONDS=21600
    restart: always

Replace the UUID and Key values. Replace both generate-a-long-random-token values with the same long random token, then run:

docker compose up -d

The Resplendent updater sidecar can update the sync agent from the Sync Agents page and checks for updates automatically when the agent reconnects.

Verify it’s working

docker compose logs -f sync-agent

You should see:

INFO:__main__:Authenticating with server
INFO:__main__:Successfully authenticated with the server

Back in Resplendent, the Last Connection field on the Sync Agents page should update to show the current time. The agent sends a heartbeat every 30 seconds.

---

Part 3: Install the CData Gateway (Windows)

Requirements

• Windows machine where QuickBooks Desktop is installed
• QuickBooks Desktop must be running during syncs
• Administrator access

Installation

1. Download the CData QuickBooks Desktop Gateway from: https://www.cdata.com/products/quickbooksgateway/

2. Run the installer

3. The Gateway Control Panel opens after installation. If not, find “CData QuickBooks Desktop Gateway” in the Start Menu.

---

Part 4: Configure the Gateway

Create a Gateway user

1. Open the CData QuickBooks Desktop Gateway
2. Go to the Users tab
3. Click Add User
4. Enter a username (e.g., resplendent) and a password
5. Click Save

Write down the username and password. You’ll enter these in Resplendent later.

Configure the service

1. Go to the Service tab
2. Note the Port (default: 8166)
3. SSL is not required for local connections — the sync agent runs on the same network, so HTTP is fine
4. Note the URL shown (e.g., http://192.168.1.100:8166)
5. Click Start Service

Authorize QuickBooks access

1. Open QuickBooks Desktop as an administrator
2. In the Gateway, go to the Connection tab
3. Click Connect to QuickBooks
4. QuickBooks shows an authorization prompt — select “Yes, always allow access”
5. Verify the status shows “Connected”

QuickBooks must be open and logged in whenever a sync runs. If it’s closed, syncs will fail with a “QuickBooks not responding” error.

---

Part 5: Connect in Resplendent

1. In Resplendent, go to Settings → Integrations
2. Find QuickBooks Desktop. Click Connect, or select Manage → New connection if you already have a QuickBooks Desktop connection
3. Enter your Gateway details:
   • Gateway URL: The URL from Part 4 (e.g., http://192.168.1.100:8166)
   • Gateway User: The Gateway user from Part 4
   • Gateway Password: The password you created
4. Enter a required Connection Title. The Description is optional
5. Scroll down to On-Premise Sync Agent
6. Toggle Enable On-Premise Sync
7. Under Select Sync Agent, choose your sync agent
8. Click Save & Test

If the test succeeds, you’ll see a green “Connected” status. Click Sync Dataset to choose which QuickBooks tables to sync.

---

Managing the sync agent

Common commands (run from the directory containing docker-compose.yaml):

# View logs
docker compose logs -f sync-agent

# Restart the agent
docker compose restart sync-agent

# Stop the agent
docker compose down

# Pull latest version manually
docker compose pull && docker compose up -d

---

Troubleshooting

”Network unreachable” or connection timeout

• Verify the Linux VM can reach the Windows machine: ping <windows-ip>
• Check Windows Firewall allows inbound connections on port 8166
• Make sure the Gateway service is running (check the Service tab)

“Authentication failed”

• Verify the username and password match what you created in the Gateway
• Check the Gateway URL matches (http vs https if you enabled SSL)

“QuickBooks not responding”

• Make sure QuickBooks Desktop is open and logged into a company file
• Verify the Gateway shows “Connected” in the Connection tab
• Try clicking Connect to QuickBooks again in the Gateway

Sync agent not connecting

• Check Docker is running: docker ps
• Verify the UUID and Key in docker-compose.yaml match what’s in Resplendent
• Check logs for authentication errors: docker compose logs sync-agent

Agent shows “Never connected” in Resplendent

• The agent might not have started. Check docker compose ps
• Outbound WebSocket connections might be blocked. The agent connects to wss://app.resplendentdata.com on port 443
• DNS issues: try adding dns: [8.8.8.8, 1.1.1.1] under the sync-agent service

---

Security notes

1. HTTP is fine for local connections — The sync agent runs on your local network, so HTTPS isn’t required. If you prefer encryption, you can enable SSL in the Gateway settings.
2. Restrict Gateway access — Configure Windows Firewall to only allow the sync agent’s IP on port 8166
3. Use strong passwords — The Gateway user password protects access to your QuickBooks data
4. Keep software updated — The sync agent updates automatically; update QuickBooks and the Gateway manually
5. Docker socket access — The sync-agent-updater service mounts the Docker socket (/var/run/docker.sock) to manage container updates. This grants it privileged access to control containers on the host. The group_add value should match the Docker socket group ID, which is usually 999 and can be checked with stat -c '%g' /var/run/docker.sock. Some enterprise security policies may prohibit socket access. If you need manual update control, remove the updater service and run docker compose pull && docker compose up -d to update manually.

The sync agent only makes outbound connections. It doesn’t open any inbound ports or accept incoming connections.

---

Support

If you’re stuck, email support@resplendentdata.com with:

• Sync agent logs (docker compose logs sync-agent)
• Screenshot of the Gateway’s Connection tab
• Any error messages from the Resplendent UI

---

Related topics

• QuickBooks integration overview
• Managing synced datasets
• Data management settings