Sync Agents

Sync agents let you connect data sources that aren’t accessible from the public internet—things like QuickBooks Desktop, local SQL Server instances, or databases behind a corporate firewall.

How it works

The sync agent is a Docker container that runs on your network. It connects outbound to Resplendent’s cloud over WebSocket, waits for sync requests, queries your local data source, and sends the results back.

┌─────────────────────────────────────────────────────────────────┐
│                      Your network                               │
│                                                                 │
│  ┌──────────────────┐         ┌──────────────────────────────┐  │
│  │   Sync Agent     │ ◄─────► │   Local data source          │  │
│  │   (Docker)       │         │   (QuickBooks, SQL Server)   │  │
│  └────────┬─────────┘         └──────────────────────────────┘  │
│           │                                                     │
└───────────│─────────────────────────────────────────────────────┘
            │ WebSocket (outbound only, port 443)
            ▼
    ┌───────────────────┐
    │  Resplendent      │
    │  Cloud            │
    └───────────────────┘

Because the agent only makes outbound connections, you don’t need to open any inbound firewall ports or configure port forwarding.

---

When you need a sync agent

You need a sync agent if your data source:

• Runs on a local machine (QuickBooks Desktop)
• Is behind a firewall with no public IP
• Can’t whitelist Resplendent’s IP addresses
• Is on a private network segment

For cloud services (ConnectWise, QuickBooks Online, Autotask) or databases with public IPs, you don’t need a sync agent—connect directly through the Integrations page.

---

Creating a sync agent

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

1. Go to Settings → Sync Agents in the sidebar
2. Click Add Sync Agent
3. Enter a name for your agent (e.g., “Office Server” or “HQ Sync Agent”)
4. Click Save

The dialog displays 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 to install the agent.

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

---

Installing the agent

Requirements

• A 64-bit x86 (amd64) machine with Docker Engine and Docker Compose v2 installed
• Network access to your local data source
• Outbound HTTPS and WebSocket access to app.resplendentdata.com on TCP port 443

We recommend a dedicated Linux VM or server that stays running 24/7. The agent needs to be online whenever syncs run. Windows with WSL2 and macOS can be used for evaluation, but Linux is the recommended production host.

Use the following profiles to size each sync agent host:

Workload	CPU	Memory	Available SSD storage	Network
Evaluation or light use	2 vCPU	4 GB RAM	20 GB	10 Mbps
Recommended production	4 vCPU	8 GB RAM	40 GB	100 Mbps
Large backfills or multiple data sources	8 vCPU	16 GB RAM	80 GB	100 Mbps–1 Gbps

These profiles are planning recommendations rather than fixed limits. Actual resource use depends on the number of simultaneous syncs, selected columns, row width, and the volume of changes between syncs. Large initial imports and incremental catch-up operations can temporarily use substantially more memory and network bandwidth than normal scheduled syncs.

The agent does not store a persistent copy of synchronized data on the host. Available storage is primarily used for Docker images, container logs, and temporary capacity while an updated image is downloaded. Configure Docker log rotation and leave enough free space for both the current and replacement images during an update.

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, then creates a docker-compose.yaml and starts the containers.

Manual install

If you prefer not to pipe scripts to bash:

1. Create a directory for the agent:

   mkdir resplendent_sync_agent
   cd resplendent_sync_agent

2. Create docker-compose.yaml:

   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

3. Replace your-uuid-here and your-key-here with your actual credentials. Replace both generate-a-long-random-token values with the same long random token. If the Docker socket group on your host is not 999, replace group_add with the output of stat -c '%g' /var/run/docker.sock.

4. Start the containers:

   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.

Security considerations

The configuration above uses :latest tags and remote update checks for convenience. For production or security-sensitive environments, consider:

• Pin to specific versions: Use image digests or version tags (e.g., resplendentdata/sync-agent:1.2.3) instead of :latest to control when updates occur.
• Review before updating: Disable the updater sidecar and manually pull new versions after reviewing changelogs.
• Monitor updates: Set up alerts for container restarts so you know when updates are applied.

Docker socket access

The sync-agent-updater service mounts the Docker socket (/var/run/docker.sock:/var/run/docker.sock), which grants it privileged control over containers on the host. This is required for remote updates but can be a security risk in enterprise environments.

For locked-down deployments:

• Disable remote updates: Remove the sync-agent-updater service block and the sync-agent updater environment variables, then update manually with docker compose pull && docker compose up -d.
• Use a dedicated update pipeline: Integrate container updates into your existing CI/CD or patch management process instead of using the updater sidecar.
• Restrict socket access: If the updater is required, consider running it with reduced privileges or using a Docker socket proxy that limits which operations are allowed.

Verify the connection

Check the logs to confirm the agent connected:

docker compose logs -f sync-agent

You should see:

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

In Resplendent, the Last Connection column on the Sync Agents page should show the current time. The agent sends a heartbeat every 30 seconds.

---

Using the agent with an integration

Once your agent is running, you can use it when connecting a data source:

1. Go to Settings → Integrations
2. Find the integration card (e.g., QuickBooks Desktop). Click Connect, or select Manage → New connection if the card already has a connection
3. Fill in the connection details and the required Connection Title
4. Scroll down to On-Premise Sync Agent
5. Toggle Enable On-Premise Sync
6. Under Select Sync Agent, choose your agent
7. Click Save & Test

The connection test runs through your sync agent. After the dialog shows Connected, click Sync Dataset to select the datasets you want to sync.

---

Managing agents

Common commands

Run these 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

# Update manually
docker compose pull && docker compose up -d

Editing an agent

1. Go to Settings → Sync Agents
2. Click the agent name
3. Update the name if needed
4. Click Save

You can’t change the UUID or Key after creation. If you need new credentials, delete the agent and create a new one.

Deleting an agent

You must be an Admin user to delete a sync agent.

1. Go to Settings → Sync Agents
2. Click the agent name
3. Click Delete

You can’t delete an agent that’s still assigned to an integration. First go to Settings → Integrations, edit or delete each connection that uses the agent, and save the changes so the connection no longer uses that agent.

---

Troubleshooting

Agent shows “Never connected”

• Check the container is running: docker ps
• Verify the UUID and Key match what’s in Resplendent
• Check logs for errors: docker compose logs sync-agent
• Ensure outbound connections to wss://app.resplendentdata.com on port 443 aren’t blocked

”Connection refused” when testing integration

• Verify the sync agent can reach your data source on the network
• Check firewall rules between the agent and data source
• For QuickBooks Desktop, ensure the CData Gateway is running

Agent keeps disconnecting

• Check for network instability
• The agent automatically reconnects after disconnection
• If the problem persists, check docker compose logs sync-agent for error patterns

---

Integration-specific guides

For detailed setup instructions with specific data sources:

• QuickBooks Desktop on-premise setup — Includes CData Gateway installation

---

Tier availability

Sync agents are available on Business tier and above. See Tier Limits for details.

---

Frequently asked questions

Does the sync agent require inbound firewall ports?

No. The agent only makes outbound connections to Resplendent’s cloud on port 443 (HTTPS/WSS). No inbound ports, port forwarding, or firewall rules are needed.

What happens if the agent goes offline?

Syncs pause until the agent reconnects. The agent automatically reconnects when the network is restored. No data is lost.

Can I run multiple sync agents?

Yes. Create a separate agent in Resplendent for each location or network segment. Each agent needs its own UUID and Key.

How do I update the sync agent?

The Resplendent updater sidecar can update the sync agent from the Sync Agents page and checks for updates automatically when the agent reconnects. For manual updates: docker compose pull && docker compose up -d.

What are the system requirements?

For production, we recommend a dedicated 64-bit x86 Linux VM with 4 vCPU, 8 GB RAM, 40 GB of available SSD storage, and a 100 Mbps network connection. The minimum profile for evaluation or light workloads is 2 vCPU, 4 GB RAM, and 20 GB of available storage. See Requirements for high-volume sizing and network details.

Can I see sync agent logs in Resplendent?

Basic connection status appears in Settings → Sync Agents. For detailed logs, check the container directly: docker compose logs -f sync-agent.