> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zwiron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Zwiron Agent

> Deploy the Zwiron outbound-only agent on a server, Docker, or Kubernetes for private VPC and on-prem sync.

<Info>
  **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](/concepts/execution-modes) to decide which fits your setup.
</Info>

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:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/zwiron/agent/main/install.sh | sudo sh
```

Then register with your token:

```bash theme={null}
sudo zwiron-agent install --token <YOUR_TOKEN>
```

The installer will:

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

**Verify it's running:**

```bash theme={null}
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.

```bash theme={null}
docker run -d \
  --name zwiron-agent \
  --restart unless-stopped \
  -e ZWIRON_TOKEN=<YOUR_TOKEN> \
  ghcr.io/zwiron/agent:latest
```

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

```bash theme={null}
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.

```yaml theme={null}
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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Agent shows as offline in the dashboard">
    Check that the agent service is running: `sudo zwiron-agent status`

    If it's stopped: `sudo systemctl start zwiron-agent` (Linux) or `sudo launchctl start zwiron-agent` (macOS)

    Check logs for errors: `sudo zwiron-agent logs`
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>