Hybrid Deployment Mode

Hybrid mode runs an agent inside your own network. A connection you assign to that agent is extracted on your LAN — the source data is read, staged, and loaded to your Snowflake by the agent, and never transits Elglide's cloud. The agent makes only outbound connections; you open no inbound ports to us. The control plane (scheduling, monitoring, retries) still runs in the Elglide cloud, so the experience is identical to normal SaaS.

Included for every account. Hybrid mode is part of the flat rate — there is no plan to upgrade to. The "Hybrid Agent" connectivity option and the Agents page are available to every tenant. See pricing.

Architecture

Two trust zones split by your firewall. Only one outbound channel crosses it — your data stays on your side.

The agent dials out over mutual-TLS; only instructions, metadata and logs cross the firewall, never your rows.

When to use it

Your security policy forbids any source data leaving your network — even transiently.
You can't allowlist our egress IPs and would rather not run an SSH bastion.
You have a host (VM or Docker host) inside your network that can reach both your sources and the public internet outbound.
Your files sit on a Windows or NAS share, or in a folder on a server — those are read only by an agent.

Hybrid is per connection — you can route one source through an agent and keep others Direct or over SSH. Your Snowflake destination is never routed through the agent: the agent uploads the staged files to your Snowflake directly, and Elglide's cloud runs the COPY and MERGE statements that move them into your tables.

Setup

1. Register the agent

Go to Tenant Settings → Hybrid Agents (sign-in required) and add an agent. Give it a name and an agent group number (e.g. 1). Connections route to a group, not to a specific agent — any healthy agent in the group can serve them.

Requirement — a group is a reachability boundary. Every agent in a group must be able to reach every source that any connection in that group targets. Agents in a group are treated as interchangeable: a connection can be served by — or failed over to — any agent in its group. So if agents in the same group disagree on what they can reach, syncs fail unpredictably depending on which agent a request lands on. If one agent can reach a database and another can't, they belong in separate groups — point each connection at the group whose agents can all reach its source. Use one group per network segment, and add a second agent to a group only when it has identical source reachability to the first.

Most tenants use a single group with one agent. You can run two or more agents in the same group so that syncs keep flowing when one host is down: if an agent's outbound channel drops (host reboot, crash, network blip) the broker places new work on another healthy agent in the group. A sync that was already running on the dropped agent fails and is retried on its normal schedule — it is not resumed mid-flight on the other agent. Keep every agent in such a group on identical source reachability. Within a group a connection prefers the same agent to reuse a warm connector (already-running container, cached images) for faster syncs, and load from many connections spreads across the group's agents.

2. Download the install package recommended

On the Hybrid Agents (sign-in required) page, click Download install package on your agent. This issues a fresh certificate and assembles a single .zip that's ready to deploy as-is: the compose files, the installer, a .env fully filled in (tenant id, agent id, group, broker URL, a generated local gateway key, and AGENT_CERT_PASSWORD), and your certificate already placed in a certs/ folder (agent.pfx + ca.crt). No manual folder, no file moves, no password to paste — just extract and run the installer (step 4).

This package contains your private key (certs/agent.pfx) and its password — it downloads once and is the only copy; Elglide never stores the key. Keep the zip safe and don't commit it to source control. The agent's identity is baked into the certificate (so it can't be impersonated); only the fingerprint/expiry are recorded on the agent for tracking. To rotate later, click Download install package again. The certificate just before it keeps working so you can install the new one without downtime; anything older is refused from then on.

The agent, gateway, and connector images are published to Elglide's public container registry, so the installer pulls them anonymously — no registry login and no AWS account, and the package never expires. Install whenever you're ready.

Advanced. A config-only bundle (no certificate inside) is still available as a direct endpoint — …/Account/Agents?handler=Bundle&id=<agent id> — for security-strict tenants who want to refresh config without cert churn. It isn't the normal path: you'd supply the certificate and AGENT_CERT_PASSWORD yourself. Most tenants should just use the Install package above.

3. Deploy the Agent + Gateway in your network

The tenant footprint is two small always-on services — the Agent (the outbound dialer) and a Gateway (routes each request to the right connector) — plus the per-vendor connectors, which start on demand when a sync needs them and idle back down. Run them on a host (or cluster) that can reach your sources and make outbound HTTPS to Elglide. No inbound ports.

With the Install package (step 2) everything below is already done — the .env is complete and your certs are in certs/. Just extract and run the installer: chmod +x install.sh && ./install.sh. Before touching anything it verifies Docker, the config, the certificate and its password, your system clock, and outbound reachability to the broker and registry — every failure names the exact fix, and re-running is always safe. For reference, the values the package fills in are:

# Pre-filled by the package (your Elglide registry + this agent's details):
GATEWAY_IMAGE / AGENT_IMAGE / BROKER_URL / TENANT_ID / AGENT_ID / AGENT_GROUP_ID / LOCAL_GATEWAY_API_KEY
# Certificate + password — also pre-filled, and the cert files already placed in ./certs:
CERT_DIR=./certs
AGENT_CERT_FILE=agent.pfx
AGENT_CERT_PASSWORD=<already set by the package>
BROKER_CA_FILE=ca.crt

Pick your platform below. (Air-gapped or no registry access? Ask your Elglide rep about mirroring the images.)

Linux recommended Kubernetes OS-independent Windows & macOS eval

A single Linux VM/host (e.g. Ubuntu/RHEL) with outbound HTTPS (TCP 443). Uses headless Docker Engine — not Docker Desktop. Recommended for production.

Install Docker Engine + Compose:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # log out/in so docker runs without sudo

Unzip the package from step 2 into a folder, e.g. /opt/elglide. Its .env is filled in for this agent and your certs are already in certs/ — nothing to edit.
Run the installer (no registry login needed — the images are public and pulled anonymously). It runs every preflight, pulls, starts the Agent + Gateway, and waits for the agent to connect; connectors are pulled and spawned on demand:
```
chmod +x install.sh && ./install.sh
```
Run on boot: on a host with systemd, the installer adds a boot unit for this agent (one per agent folder, named after it; run it with sudo or as root so it can). Combined with the agent's restart: unless-stopped policy, the agent recovers from reboots and crashes on its own — run it on an always-on host (a server or VM that isn't suspended when idle) so the connection stays live 24/7.

Upgrades: connector and gateway images follow Elglide's current release automatically (see step 7). To move the agent itself to a newer release, download a fresh install package and re-run ./install.sh.

The cleanest enterprise option, and OS-independent — it runs on any cluster regardless of node OS, and needs no Docker on your side. The same install package you downloaded in step 2 has a k8s/ folder with everything pre-wired for Kubernetes; the shared .env and certs/ in the package root are reused, so there is nothing to hand-edit. The Agent + Gateway run as Deployments, and each connector runs as its own Deployment — idle at replicas: 0 and scaled up on demand per sync.

Prerequisites. A cluster whose nodes can make outbound HTTPS (TCP 443), and kubectl pointed at it (kubectl config current-context). That's all — no Docker, no cluster-side install, no inbound ports.

Unzip the package from step 2 and switch into its Kubernetes folder:

unzip elglide-hybrid-ready-<agent>.zip -d elglide-hybrid
cd elglide-hybrid/k8s

Run the installer. It creates the elglide namespace and the cert / gateway-key secrets (from the shared ../.env and ../certs; the images are public, so no image-pull secret is needed), applies the manifests, and waits for the agent to connect:
```
chmod +x install.sh && ./install.sh
```
Options: ./install.sh --always-on runs connectors 24/7 instead of on-demand (see below); ./install.sh --namespace my-ns installs into a different namespace.

On SUCCESS the installer prints that the agent connected, and the Agents page shows this agent as Connected. Outbound 443 only; no Ingress.

Start / stop the agent. The Agent is a Deployment — there is no agent.sh in Kubernetes, so you start and stop it by scaling its replica count. Your cluster keeps it running (and restarts it after a node reboot) on its own:

kubectl -n elglide scale deploy/agent --replicas=1   # start
kubectl -n elglide scale deploy/agent --replicas=0   # stop
kubectl -n elglide get pods
kubectl -n elglide logs deploy/agent -f              # healthy: "Release manifest received…"

You only ever scale deploy/agent — leave the connector Deployments alone.

Connector modes. Two ways to run the connectors — the default suits most tenants:

On-demand (default). Connectors sit at replicas: 0; the Agent scales the matching one 0→1 (via the in-cluster API, scoped RBAC — no Docker socket, no root) before a sync and back to 0 once idle (Agent__ConnectorIdleTimeoutSeconds, 600s). Elastic cost; nothing runs for a connector you're not using.
Always-on (./install.sh --always-on). Connectors run at replicas: 1 permanently and the Agent uses External mode — no scaling RBAC granted at all. Choose this if your platform team manages connector uptime via GitOps and would rather not give the Agent any scaling permissions.

On-demand doesn't auto-create connectors. The installer registers a Deployment (at replicas: 0) for every engine up front; on-demand only scales an already-registered one 0↔1, it never creates one on first use. That's why all six ship registered (SQL Server, PostgreSQL, MySQL, Oracle, File, REST) — an unused connector at replicas: 0 costs nothing. Trim connectors.yaml before installing if you want fewer. The File connector mounts a PersistentVolumeClaim named elglide-source-files read-only; point it at your own NFS/CIFS volume (or a hostPath on a single-node cluster) before using a file source.

Air-gapped or no registry access? Ask your Elglide rep about mirroring the images into your own registry.

For trying hybrid on a workstation with Docker Desktop. Not a production runtime — use the Linux or Kubernetes option for real deployments.

The agent, gateway, and connector images are Linux containers; Docker Desktop provides the Linux runtime on both Windows and macOS.

Install Docker Desktop (Windows: WSL2 backend with Linux containers; macOS: default install).
Unzip the package from step 2 — the .env and ./certs are already complete.
Run the installer (no registry login needed — the images are public and pulled anonymously). On macOS use Terminal; on Windows use a Git Bash or WSL shell (Docker Desktop's docker CLI is available in both):
```
chmod +x install.sh && ./install.sh
```

Why Windows is eval-only. Docker Desktop only runs while you're logged in, and the WSL2 VM it relies on suspends when idle — either takes the agent offline (the Agents page flips to Not connected). Running native Docker Engine inside a WSL2 distro doesn't escape this — the same idle-suspend applies — so we no longer document it as an option. For production on a Windows-only estate, run a small always-on Linux VM (see the Linux tab) or use Kubernetes.

Apple Silicon (M-series) Macs. The agent, gateway, and connector images are linux/amd64, so on an Arm Mac they run under emulation — enable Rosetta in Docker Desktop → Settings → General → "Use Rosetta for x86/amd64 emulation." It works but is slower than a native amd64 host, which is another reason eval-only. Intel Macs need nothing extra.

Host sizing. The Agent and Gateway are lightweight; size the host for the connectors. 2 vCPU and 4 GB RAM is a comfortable starting point, plus free disk for the staged Parquet of the largest table being synced — each extract is written locally, uploaded to your Snowflake stage, then deleted. Advanced settings are environment variables with a double underscore (e.g. Agent__BrokerUrl); the install package sets every one you need.

Evaluating on one machine (source DB on the same host)? Set the connection's Host to host.docker.internal — a container's localhost is the container, not your machine — and allow the Docker subnet through your host firewall on the DB port. In a real deployment the connectors and source DB share the LAN, so Host is just the DB's normal address.

4. Verify the agent is online

On start, the agent dials out to Elglide over mutual TLS and keeps a single long-lived outbound connection open (with heartbeats). No inbound port is opened. Two confirmations: the installer prints SUCCESS, and the Hybrid Agents (sign-in required) page shows the agent's live Status badge as Connected (it updates automatically). If it can't connect it retries with backoff — the badge flips the moment it succeeds. Stuck on Not connected? Run ./agent.sh logs on the agent host for the exact error; the usual causes are outbound TCP 443 blocked (or 8443, for a package installed before 2026-10-25), a wrong BROKER_URL, or clock skew. If the installer says The broker REFUSED this agent, it prints the reason: install the package you downloaded last (a newer download retires older certificates), or re-activate the agent on the Agents page if it was deactivated.

5. Route a connection through the agent

Open (or create) a source connection. In the Connectivity section choose Hybrid Agent (in-network) and pick the agent group from step 1. Save. The connection's effective connectivity becomes HybridAgent — every extract for it now routes to your in-network agent. (The agent-group list is empty until you have at least one registered agent.)

In-network source specifics. Because the source lives on your LAN, Elglide's cloud can't reach it directly — Test Connection and database discovery run through your agent instead. So:

Use Test Connection as usual; it reaches the source via the agent. The first test after a quiet period can take up to a minute while the agent starts the connector — if it times out, run it once more.
If your SQL Server presents a self-signed certificate, enable Trust Server Certificate in the connection's Encryption & TLS section (otherwise the login fails with an untrusted-certificate-chain error).

6. Run a sync

Trigger the connection's task as usual. The extract runs entirely inside your network: the agent reads the source, stages the data to your Snowflake, and Elglide's cloud orchestrates and audits the run without ever touching the rows. You'll see the run, metrics, and audit in the portal exactly like a normal sync.

7. Operate (day-2)

The install package includes one helper next to the installer — no Docker knowledge needed: chmod +x agent.sh once, then ./agent.sh <command> from the install folder (on Windows, from the same Git Bash or WSL shell you installed from).

Command	What it does
`./agent.sh status`	Show the agent + gateway container status.
`./agent.sh logs`	Follow the agent's live log (Ctrl+C to stop).
`./agent.sh stop` / `start`	Pause and resume the agent (containers kept; a stopped agent stays stopped across reboots). The Agents page badge flips to Not connected / Connected accordingly.
`./agent.sh update`	Re-pull the images your package pins and restart. Connector and gateway images already follow Elglide's current release on their own (below), so this is rarely needed. To move the agent itself to a newer release, download a fresh install package and re-run `./install.sh`. If a pull fails, check that outbound HTTPS (443) to the registry isn't blocked by a firewall/proxy, then retry.
`./agent.sh uninstall`	Stop and remove the containers and the agent's start-on-boot service (your config + certificate stay in the folder). Also deactivate the agent on the Agents page.

Prefer raw Docker? From the install folder, these work on any OS:

docker compose -f docker-compose.tenant.yml --env-file .env ps          # status
docker compose -f docker-compose.tenant.yml --env-file .env logs -f agent   # follow logs
docker compose -f docker-compose.tenant.yml --env-file .env stop            # stop
docker compose -f docker-compose.tenant.yml --env-file .env start           # start

The best health signal is still the Hybrid Agents page badge, which reflects the live broker session rather than just whether the container is up.

How updates reach you. Elglide publishes the approved image versions to your agent over its existing outbound channel. Connectors pick up the current version the next time one is started for a sync, and the Gateway is updated by the agent only while nothing is in flight — a running sync is never interrupted, and nothing new is opened inbound. The agent itself does not self-update: to move it to a newer release, download a fresh install package and re-run ./install.sh. The Agents page shows the version each container is running and flags one that is behind.

8. Certificate lifecycle

Where it lives. The certificate and its private key exist only in the install package you download (certs/agent.pfx) — Elglide keeps no copy. The Agents page records just the SHA-256 fingerprint and expiry date for tracking. Certificates are issued by Elglide's private CA at no charge, valid for ~2 years.

Renewal (before or after expiry) — same as install:

On the Hybrid Agents (sign-in required) page, click Install package for the agent — every download issues a fresh certificate (the fingerprint/expiry in the table updates).
Extract the zip over the existing folder on the agent host.
Run ./install.sh — it swaps in the new certificate and password and restarts; the agent reconnects and the Status badge turns Connected.

If the certificate already expired, the agent simply stays disconnected until the new package is installed — the installer detects an expired certificate and prints this exact instruction. The certificate just before the new one keeps working until its own expiry, so renew ahead of the date shown in the table for zero downtime. Each download retires anything older, so always install the package you downloaded last.

Deleting an agent removes its record here (Elglide holds no key to delete). The copy in the host folder is yours — ./agent.sh uninstall removes the containers and leaves the folder; delete it manually to destroy the key material.

Networking summary

Direction	From → To	Why
Outbound	Agent → `broker.elglide.com`, TCP 443 (mutual TLS)	The only rule we need — the agent dials us. Packages installed before 2026-10-25 dial 8443, which stays open; re-download the package to move to 443.
Internal (your LAN)	Connectors → your source database, on the DB port (SQL Server 1433 · PostgreSQL 5432 · MySQL 3306 · Oracle 1521)	The connectors read the source over your LAN. This is the one rule on your side — see the note below.
Outbound	Agent host → Elglide container registry & storage (HTTPS 443)	Pulls the version-matched connector image on demand.
Outbound	Agent → your Snowflake account (HTTPS 443)	Uploads the staged files directly to your warehouse.
From Elglide	Elglide cloud → your Snowflake account	Runs the COPY, MERGE and audit statements, as in any mode. If your Snowflake account uses a network policy, it must allow Elglide as well as your agent — ask us for the current address.
Inbound	none	You open no ports to Elglide.

One firewall rule is yours to set. Everything Elglide needs is outbound — the agent dials us, so there's nothing to open toward Elglide. The rule you own is entirely LAN-internal: the agent host must be able to reach each source database on its port. That usually means a host-firewall allow on the DB port, plus the database's own access config (PostgreSQL pg_hba.conf, SQL Server TCP/IP enabled, the listener's bind address). Because connectors run as Docker containers, allow the Docker subnet through on that port. This traffic never leaves your network — and because Elglide's cloud can't reach your source, Test Connection runs through the agent, not from our cloud.

How it stays private & secure

Data residency. Source rows flow source → agent → your Snowflake. They never pass through Elglide compute.
What crosses the firewall. Down to the agent: sync instructions, and the source connection details you saved in the portal (the agent needs them to log in to your database). Up to Elglide: run status, row counts, audit results (counts and checksums, no row contents) and the agent's own log lines. Never the rows.
Host access. On Docker, the agent uses the host's Docker socket to start and stop connector containers, which is administrator-level control of that Docker host — run it on a host dedicated to Elglide. On Kubernetes no socket is used: the agent gets a namespaced role limited to scaling the six named connector Deployments.
Mutual TLS. Both sides authenticate by certificate. The agent pins Elglide's server certificate; Elglide derives the agent's identity from its client certificate — neither can be impersonated.
Outbound-only. The agent never listens. It opens one outbound connection and Elglide multiplexes work over it, so there's nothing inbound to attack.
Opt-in per connection. Hybrid routing applies only to connections you explicitly assign to an agent group — nothing else is affected.

Don't need data to stay on your LAN? The simpler paths are Direct connection — IP allowlist or an SSH bastion.