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

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

After saving, the page displays your Agent UUID and Agent Key. Copy both values—you’ll need them to install the agent.

The Agent Key only appears after the first save. If you leave the page before copying it, you can return to view it again.

---

Installing the agent

Requirements

• A machine with Docker installed (Linux, Windows with WSL2, or macOS)
• Network access to your local data source
• Outbound internet access on port 443

We recommend a dedicated Linux VM or server that stays running 24/7. The agent needs to be online whenever syncs run.

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:

   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
       labels:
         - 'com.centurylinklabs.watchtower.enable=true'
       restart: always
   
     watchtower:
       image: containrrr/watchtower
       container_name: watchtower
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
       environment:
         - WATCHTOWER_CLEANUP=true
         - WATCHTOWER_INCLUDE_RESTARTING=true
         - WATCHTOWER_ROLLING_RESTART=true
         - WATCHTOWER_POLL_INTERVAL=21600
       dns:
         - 8.8.8.8
         - 1.1.1.1
       restart: always

3. Replace your-uuid-here and your-key-here with your actual credentials.

4. Start the containers:

   docker compose up -d

Watchtower automatically updates the sync agent every 6 hours when new versions are released.

Security considerations

The configuration above uses :latest tags and automatic updates via Watchtower 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 Watchtower auto-updates 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 Watchtower service mounts the Docker socket (/var/run/docker.sock:/var/run/docker.sock), which grants it privileged control over all containers on the host. This is required for automatic updates but can be a security risk in enterprise environments.

For locked-down deployments:

• Disable Watchtower: Remove the entire watchtower service block from docker-compose.yaml and 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 relying on Watchtower.
• Restrict socket access: If Watchtower 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 Data Settings → Integrations
2. Click Connect on the integration card (e.g., QuickBooks Desktop)
3. Fill in the connection details
4. Scroll down to On-Premise Sync Agent
5. Toggle Enable On-Premise Sync
6. Select your agent from the list
7. Click Save & Test

The connection test runs through your sync agent. If it succeeds, you can start syncing datasets.

---

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 (Watchtower does this automatically)
docker compose pull && docker compose up -d

Editing an agent

1. Go to Data 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

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

You can’t delete an agent that’s still assigned to an integration. Remove the agent from all integrations first.

---

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?

Watchtower (included in the Docker Compose file) automatically pulls new versions every 6 hours. For manual updates: docker compose pull && docker compose up -d.

What are the system requirements?

Any machine with Docker that can reach your data source and has outbound internet access. We recommend a dedicated Linux VM with at least 1GB RAM. The agent is lightweight.

Can I see sync agent logs in Resplendent?

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