> ## 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.

# The Zwiron Agent

> What the Zwiron agent does for private-network sync — outbound-only, mTLS, no inbound ports required.

<Info>
  The agent is only needed for **Agent mode** — when your databases are in a private network or VPC. If you're connecting cloud services with public endpoints (Snowflake, BigQuery, RDS public, etc.), you can use **Hosted mode** and skip agent installation entirely. See [Execution Modes](/concepts/execution-modes).
</Info>

The **Agent** is the core runtime for in-network pipelines. It's a single binary that runs inside your infrastructure and handles all actual data movement.

***

## Why an agent?

When you need sync to stay in your network — private VPC, on-prem, or compliance — the agent runs **in your infrastructure**. Row data moves from source to destination there. The control plane handles scheduling and receives metadata (row counts, status), not the synced rows.

For cloud sources with public endpoints, you can skip the agent and use [Hosted mode](/concepts/execution-modes).

***

## What the agent does

* **Receives jobs** from the Zwiron control plane via an encrypted, persistent connection
* **Connects to your databases** using credentials decrypted locally with the agent's RSA key
* **Reads data** from sources using optimized batch queries or change data capture
* **Writes data** to destinations using high-throughput bulk loading where available
* **Reports progress** — row counts, bytes moved, timing — back to the dashboard in real time
* **Manages its own keys** — generates an RSA key pair on first install; used to encrypt credentials and authenticate with the control plane

***

## Agent lifecycle

```
Install → Register → Idle → Receive job → Execute → Report → Idle
```

The agent stays connected to the control plane with a persistent outbound stream. When idle, it costs almost no resources. When a job is dispatched, it wakes up, executes the sync, and returns to idle.

***

## Credentials and security

When you save an Agent-mode connection in the Zwiron dashboard:

1. Credentials are encrypted with the agent's public RSA key
2. Atlas stores the ciphertext; the agent also keeps a local encrypted copy
3. When a job runs, the agent decrypts credentials **in memory** for the sync — plaintext is not sent back to Zwiron

This means:

* Zwiron cannot read Agent-mode passwords without the agent's private key
* Deleting an agent makes its local credential material irrecoverable
* For Hosted mode, credentials are encrypted and used on Zwiron's infrastructure — see [Connections](/concepts/connections)

***

## Multiple agents

You can run multiple agents — one per environment, one per network segment, or one per team. Each agent is independently registered and shows up in **Settings → Agents**.

Use cases for multiple agents:

* Separate staging and production agents
* One agent in your AWS VPC, another for on-prem databases
* Isolated agents per team for access control

***

## Agent health and monitoring

The agent sends a heartbeat to the control plane every few seconds. If the heartbeat stops, the agent shows as **Offline** in the dashboard.

Check agent status at any time:

```bash theme={null}
sudo zwiron-agent status
```

Stream live logs:

```bash theme={null}
sudo zwiron-agent logs
```

***

## Updating the agent

```bash theme={null}
sudo zwiron-agent update
```

This downloads and installs the latest version, then restarts the service. The agent will reconnect automatically.

***

## Uninstalling

```bash theme={null}
sudo zwiron-agent uninstall
```

This removes the binary, stops the service, and deregisters the agent from your account. Any connections associated with this agent will stop working.

***

## Resources used

The agent is designed to be lightweight:

| Resource             | Typical usage                                                    |
| -------------------- | ---------------------------------------------------------------- |
| CPU (idle)           | \< 1%                                                            |
| Memory (idle)        | \~30 MB                                                          |
| Memory (during sync) | Proportional to batch size (\~50–500 MB for large tables)        |
| Disk                 | Minimal — just the binary, keys, and a small checkpoint database |
| Network              | Outbound only, port 443                                          |

***

## Installation options

See the full [Agent installation guide](/getting-started/install-agent) for instructions on installing via script, Docker, or Kubernetes.