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.

Plan availability. Hybrid mode is included with the plans that list Hybrid deployment on the pricing page. The "Hybrid Agent" connectivity option and the Agents page appear only for tenants on those plans. Compare plans.

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 control + metadata + logs cross the firewall, never your data.

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 source databases and the public internet outbound.

Hybrid is per connection — you can route one source through an agent and keep others Direct or over SSH. Snowflake targets always stay cloud-side.

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; run two or more agents in the same group for high availability. If an agent's outbound channel drops (host reboot, crash, network blip) the broker routes its connections to another healthy agent in the same group — so keep every agent in an HA 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 previous cert keeps working until you deactivate the agent).

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 source databases 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 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: a one-line systemd unit (ExecStart=/usr/bin/docker compose -f /opt/elglide/docker-compose.tenant.yml up) starts it automatically. 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: ./agent.sh update (or docker compose pull && docker compose up -d).

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 with outbound 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: "Hybrid channel UP… as tenant <id>"

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 four ship registered — an unused connector at replicas: 0 costs nothing. Trim connectors.yaml before installing if you want fewer.

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.

Config keys map to environment variables with a double underscore (e.g. Agent__BrokerUrl), or live under an "Agent" section in a config file. Your Elglide representative provides the signed deployment bundle for your platform.

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 8443 blocked, a wrong BROKER_URL, or clock skew.

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 option appears only for tenants on a plan that includes hybrid deployment with at least one registered agent.)

In-network source specifics. Because the source lives on your LAN, Elglide's cloud can't reach it to browse databases or run Test Connection from this page — that's expected and not an error. So:

Type the database name directly (rather than picking from a discovered list), and skip the cloud Test Connection — your agent validates and connects on the first run.
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`	Pull the latest images and restart. The images are public and pulled anonymously, so pulls never expire; 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 (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.

Connector/agent updates today are pull-based, not pushed. Because the agent only dials out to the Broker (no inbound path), Elglide cannot push a new connector or agent image to a running host — the tenant (or their `agent.sh update` / a cron'd equivalent) has to pull it. Deferred idea, not built: use the existing persistent Broker↔Agent channel to notify the agent that a newer image is available, and have the agent self-initiate the pull + recreate once idle (checking `HasActiveRequests` first, same guard the idle-timeout sweep already uses, so a live sync is never interrupted) — or simpler, have the agent poll the registry for a newer digest on its own schedule with no Broker involvement at all. Revisit if staying current on connector fixes/security patches becomes a real support burden.

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 previous certificate keeps working until its own expiry, so renew ahead of the date shown in the table for zero downtime.

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 → Elglide endpoint, TCP 443 (TLS)	The only rule we need — the agent dials us.
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	Stages + loads data directly to your warehouse.
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.
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.
Fail-closed. Hybrid routing is restricted to tenants on a plan that includes hybrid deployment and 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.