Install the Zwiron Agent

Agent installation is only required for Agent mode. If your source and destination are cloud services reachable over the internet (Snowflake, BigQuery, RDS with a public endpoint, SaaS APIs), you can use Hosted mode and skip this page entirely. See Execution Modes to decide which fits your setup.

The Zwiron Agent is a lightweight binary that runs inside your network. It:

Connects outbound to Zwiron — no inbound ports required
Reads data from your sources and writes to your destinations
Decrypts Agent-mode credentials locally for syncs (RSA key unique to the agent)
Runs as a background system service (auto-starts on reboot)

Prerequisites

Requirement	Detail
Operating system	Linux (amd64 or arm64) or macOS (amd64 or arm64)
Network access	Outbound HTTPS on port 443 to `agent.zwiron.com`
Agent token	Found in Settings → Agents → New Agent in the app

Option 1 — Install script (recommended)

The fastest way to get started on any Linux server or Mac:

curl -fsSL https://raw.githubusercontent.com/zwiron/agent/main/install.sh | sudo sh

Then register with your token:

sudo zwiron-agent install --token <YOUR_TOKEN>

The installer will:

Detect your OS and CPU architecture
Download the latest agent binary
Install it to /usr/local/bin/zwiron-agent
Register it as a systemd service (Linux) or launchd service (macOS)
Start the service automatically

Verify it’s running:

sudo zwiron-agent status

Option 2 — Docker

Run the agent as a Docker container. Useful when you want container-level isolation or you’re already running Docker on your host.

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

The agent stores its RSA keys in /data inside the container. Mount a volume if you want keys to persist across container restarts.

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

Option 3 — Kubernetes

Deploy the agent as a Deployment in your cluster. This is recommended for production environments.

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: ghcr.io/zwiron/agent:latest
          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

Create the token secret first:

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

Agent commands

Command	What it does
`zwiron-agent install --token <TOKEN>`	Register and install the agent as a service
`zwiron-agent status`	Show current status, version, and connection state
`zwiron-agent logs`	Stream live agent logs
`zwiron-agent run`	Run the agent in the foreground (for debugging)
`zwiron-agent uninstall`	Remove the agent and deregister from the dashboard
`zwiron-agent update`	Update to the latest version

How the agent connects

The agent uses a persistent outbound gRPC stream to Zwiron. This means:

No inbound firewall rules needed
Works behind NAT, corporate firewalls, and VPNs
If the connection drops, the agent reconnects automatically with exponential backoff

All communication is encrypted with TLS. Agent-mode database credentials are encrypted with an RSA key unique to your agent — Zwiron stores ciphertext and cannot read plaintext without the agent’s private key.

Managing multiple agents

You can install multiple agents — for example, one per environment (staging, production) or one per network segment. Each agent shows up independently in your dashboard under Settings → Agents. When creating a connection, you select which agent should handle that connection. This lets you route traffic precisely — for example, keeping production data on its own agent.

Troubleshooting

Agent shows as offline in the dashboard

Check that the agent service is running: sudo zwiron-agent statusIf it’s stopped: sudo systemctl start zwiron-agent (Linux) or sudo launchctl start zwiron-agent (macOS)Check logs for errors: sudo zwiron-agent logs

Connection test fails

The agent runs inside your network and connects to your databases directly. Ensure:

The database host is reachable from the machine where the agent is running
The database port is not blocked by a local firewall
The database user has the required permissions (see the connector-specific guide for your database)

Outbound connection to Zwiron is blocked

The agent needs outbound access on port 443 to agent.zwiron.com. Check your egress firewall rules and proxy settings.

Getting Started

Guides

Core Concepts

Pipelines

Connectors

Platform

Support

Install the Zwiron Agent

Prerequisites

Option 1 — Install script (recommended)

Option 2 — Docker

Option 3 — Kubernetes

Agent commands

How the agent connects

Managing multiple agents

Troubleshooting

​Prerequisites

​Option 1 — Install script (recommended)

​Option 2 — Docker

​Option 3 — Kubernetes

​Agent commands

​How the agent connects

​Managing multiple agents

​Troubleshooting

Prerequisites

Option 1 — Install script (recommended)

Option 2 — Docker

Option 3 — Kubernetes

Agent commands

How the agent connects

Managing multiple agents

Troubleshooting