Install & Use the Zwiron Agent

Agent installation is only required for Agent mode. If your source and destination are reachable over the internet (Snowflake, BigQuery, public RDS, SaaS APIs), use Hosted mode and skip this page. See Hosted vs Agent or When to use the agent.

The Zwiron Agent is a lightweight binary that runs inside your network. Sync work happens on the agent; it dials outbound only to Zwiron — no inbound ports, VPN hairpin, or firewall holes on your side.

Product downloads: zwiron.com/download/agent
Official Docker image: zwiron/agent on Docker Hub — docker pull zwiron/agent:latest

What you get

Outbound connection to the control plane (HTTPS / gRPC on port 443)
Sync execution next to your data (full refresh, incremental, CDC)
Agent-mode credentials decrypted locally with the agent’s RSA key
System service that auto-starts on reboot (native install)
Same UI: connections, pipelines, catalog, and quality

Prerequisites

Requirement	Detail
OS	Linux (amd64/arm64), macOS (amd64/arm64), or Windows (amd64).
Network	Outbound HTTPS on port 443 to `agent.zwiron.com` and `downloads.zwiron.com`
Privileges	`sudo` / root for the recommended native install
Token	Create under Settings → Agents → New Agent in the app

1. Create an agent token

Sign in at zwiron.com
Open Settings → Agents
Click New Agent and copy the one-time install token

The dashboard also shows a ready-to-run install command with your token filled in.

2. Install (Linux / macOS) — recommended

curl -fsSL https://get.zwiron.com | sudo sh

This:

Resolves the latest version from https://downloads.zwiron.com/agent/channels/stable.json
Downloads zwiron-agent-<version>-<os>-<arch>.tar.gz from the CDN
Verifies the SHA-256 checksum
Installs the binary to /usr/local/bin/zwiron-agent

Pin a version (optional):

ZWIRON_VERSION=v0.12.18 curl -fsSL https://get.zwiron.com | sudo sh

Register and start the service:

sudo zwiron-agent install --token <YOUR_TOKEN>

Verify:

zwiron-agent version
sudo zwiron-agent status

You should see the agent as online under Settings → Agents.

3. Install (Windows)

Download the Authenticode-signed exe (preferred) or the zip that contains the same binary:

Artifact	URL
Windows amd64 `.exe`	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-windows-amd64.exe`
Windows amd64 `.zip`	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-windows-amd64.zip`

Latest version: stable.json · download page In an elevated PowerShell / cmd from the download folder (rename the versioned exe if you want the short name):

Rename-Item .\zwiron-agent-*-windows-amd64.exe zwiron-agent.exe -ErrorAction SilentlyContinue
.\zwiron-agent.exe install --token <YOUR_TOKEN>
zwiron-agent.exe status

Windows should show publisher Zwiron (or your company legal name on the cert). Verify:

Get-AuthenticodeSignature .\zwiron-agent.exe | Format-List Status, SignerCertificate

If Microsoft Defender SmartScreen still says “Windows protected your PC” on a newly signed release: More info → Run anyway. That warning fades as the publisher reputation builds. Chrome may also flag a rarely downloaded .exe until Safe Browsing reputation catches up — use Keep / Download suspicious file, then verify the signature above.

4. Direct downloads

Prefer a manual download? Grab signed builds from the CDN:

Platform	Artifact
Linux amd64	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-linux-amd64.tar.gz`
Linux arm64	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-linux-arm64.tar.gz`
macOS Intel	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-darwin-amd64.tar.gz`
macOS Apple Silicon	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-darwin-arm64.tar.gz`
Windows amd64 exe	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-windows-amd64.exe`
Windows amd64 zip	`https://downloads.zwiron.com/agent/<version>/zwiron-agent-<version>-windows-amd64.zip`

Latest version string: stable.json Also on each release path: checksums.txt and checksums.txt.minisig (minisign). Browse platforms on zwiron.com/download/agent.

5. Docker

Official public image on Docker Hub: zwiron/agent (linux/amd64 + linux/arm64). Quick start

docker pull zwiron/agent:latest

docker run -d \
  --name zwiron-agent \
  --restart unless-stopped \
  -v zwiron-agent-data:/data \
  -e ZWIRON_TOKEN=<YOUR_TOKEN> \
  zwiron/agent:latest

Mount /data so RSA keys and checkpoints persist across restarts. Production — pin a version (recommended):

docker pull zwiron/agent:0.12.28

docker run -d \
  --name zwiron-agent \
  --restart unless-stopped \
  -v zwiron-agent-data:/data \
  -e ZWIRON_TOKEN=<YOUR_TOKEN> \
  zwiron/agent:0.12.28

Foreground / debug:

docker run --rm -e ZWIRON_TOKEN=<YOUR_TOKEN> zwiron/agent:latest

Hub page (bookmark this): https://hub.docker.com/r/zwiron/agent

6. Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: zwiron-agent
  namespace: zwiron
spec:
  replicas: 1
  selector:
    matchLabels:
      app: zwiron-agent
  template:
    metadata:
      labels:
        app: zwiron-agent
    spec:
      containers:
        - name: agent
          image: zwiron/agent:0.12.28
          env:
            - name: ZWIRON_TOKEN
              valueFrom:
                secretKeyRef:
                  name: zwiron-agent-secret
                  key: token
          volumeMounts:
            - name: agent-data
              mountPath: /data
      volumes:
        - name: agent-data
          persistentVolumeClaim:
            claimName: zwiron-agent-pvc

kubectl create namespace zwiron
kubectl create secret generic zwiron-agent-secret \
  --from-literal=token=<YOUR_TOKEN> \
  -n zwiron

7. Use the agent day to day

Register, start, stop

Command	Purpose
`sudo zwiron-agent install --token <TOKEN>`	Register, install service, start
`sudo zwiron-agent status`	Version, service state, connection
`sudo zwiron-agent start` / `stop` / `restart`	Control the service
`sudo zwiron-agent logs`	Tail service logs
`ZWIRON_TOKEN=<TOKEN> zwiron-agent run`	Foreground (Docker / debug)
`sudo zwiron-agent update`	Self-update from the CDN stable channel
`sudo zwiron-agent uninstall`	Stop service, remove, deregister
`zwiron-agent version`	Print version
`sudo zwiron-agent reset-certs`	Clear pinned TLS certs after CA rotation

Create Agent-mode connections

Confirm the agent is online
Connections → New connection
Choose Agent execution and select this agent
Enter DB credentials (encrypted to this agent’s key)
Profile / test the connection
Create a pipeline as usual (full, incremental, or CDC)

Multiple agents

Install one agent per environment or network segment (staging vs production, AWS VPC vs on-prem). Each agent appears under Settings → Agents. Assign connections to the agent that can reach that database.

Security model (short)

Outbound-only — agent initiates connections; no inbound ports on your side
mTLS — agent authenticates to the control plane with ECDSA certificates
Credential isolation — Agent-mode DB passwords are encrypted to the agent’s RSA key; Zwiron stores ciphertext
Row data moves on your network during sync; the control plane receives operational metadata

Details: Security · The Agent concept

Troubleshooting

Agent shows offline

sudo zwiron-agent status
sudo zwiron-agent logs

On Linux: sudo systemctl status zwiron-agent
On macOS: check the launchd service via sudo zwiron-agent status

Install script or update fails

Confirm outbound access to get.zwiron.com and downloads.zwiron.com.
Check the channel and artifact:
curl -fsSL https://downloads.zwiron.com/agent/channels/stable.json

Checksum mismatch

Re-download; do not ignore checksum errors. Compare against checksums.txt for that version. Optionally verify checksums.txt.minisig with the published minisign public key in the agent repo.

Connection test fails

The agent must reach the database host/port from its machine (not from your laptop). Check security groups, local firewall, and DB user permissions for your connector.

Outbound to Zwiron blocked

Allow HTTPS 443 egress to agent.zwiron.com. Corporate proxies may need allowlisting.

Chrome or SmartScreen blocks the Windows download

The Windows agent is Authenticode-signed. Chrome Safe Browsing and SmartScreen still warn on brand-new publisher reputation. Chrome: Keep / Download suspicious file. SmartScreen: More info → Run anyway. Then verify the publisher:

Get-AuthenticodeSignature .\zwiron-agent.exe

Status should be Valid and the signer should be Zwiron (or your company legal name).

Getting Started

Guides

Core Concepts

Pipelines

Connectors

Platform

Support

Install & Use the Zwiron Agent

What you get

Prerequisites

1. Create an agent token

2. Install (Linux / macOS) — recommended

3. Install (Windows)

4. Direct downloads

5. Docker

6. Kubernetes

7. Use the agent day to day

Register, start, stop

Create Agent-mode connections

Multiple agents

Security model (short)

Troubleshooting

​What you get

​Prerequisites

​1. Create an agent token

​2. Install (Linux / macOS) — recommended

​3. Install (Windows)

​4. Direct downloads

​5. Docker

​6. Kubernetes

​7. Use the agent day to day

​Register, start, stop

​Create Agent-mode connections

​Multiple agents

​Security model (short)

​Troubleshooting

​Related

What you get

Prerequisites

1. Create an agent token

2. Install (Linux / macOS) — recommended

3. Install (Windows)

4. Direct downloads

5. Docker

6. Kubernetes

7. Use the agent day to day

Register, start, stop

Create Agent-mode connections

Multiple agents

Security model (short)

Troubleshooting

Related