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.

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). The group is how connections find their agent — connections route to a group, and any healthy agent in that group serves them. Most tenants use a single group with one agent; run two agents in the same group for high availability, or separate groups to isolate network segments.

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

The package also bundles a short-lived registry token (~12 hours) so the installer can pull the images with no registry login and no AWS account. Install the same day you download; if it lapses, just download a fresh package.

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: double-click install.cmd on Windows, or chmod +x install.sh && ./install.sh on Linux/macOS. 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 server — recommended for production

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

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

2. 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.
3. Log in to the registry (one-time, command from Elglide) and start:

   docker compose -f docker-compose.tenant.yml up -d

   This starts the Agent + Gateway; connectors are pulled and spawned on demand.
4. Run on boot (optional): a one-line systemd unit (ExecStart=/usr/bin/docker compose -f /opt/elglide/docker-compose.tenant.yml up) keeps it up across reboots.

Upgrades: docker compose pull && docker compose up -d.

Windows Server

The connector images are Linux containers, so on Windows run Docker with the WSL2 backend (Docker Desktop, or Docker CE under WSL2). A nearby Linux VM is often the simpler production choice on Windows-only estates.

1. Install Docker with the WSL2 backend and enable Linux containers.
2. Unzip the package from step 2. Its .env is pre-filled and the certs are already in certs\ — nothing to edit.
3. Double-click install.cmd — no registry login needed (the package bundles a pull token). It runs every preflight, pulls, starts, and waits for the agent to connect.

Same images and compose as Linux — only the Docker install differs.

Docker Desktop — quick evaluation only

1. Install Docker Desktop (Windows or macOS).
2. Unzip the package from step 2 — the .env and ./certs are already complete.
3. Run the installer — install.cmd on Windows, or ./install.sh on macOS/Linux. No registry login needed (the package bundles a pull token).

Same-machine source DB? 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.

Kubernetes

The cleanest enterprise option. The Agent + Gateway run as Deployments, and the connectors run as managed Deployments (no Docker socket, no root). Set Agent__ConnectorManagement=External so the Agent forwards to the connector Services instead of spawning containers itself.

1. Create a namespace and a Secret with your cert bundle + registry creds:

   kubectl create namespace elglide
   kubectl -n elglide create secret generic agent-certs \
     --from-file=agent.pfx --from-file=ca.crt
   kubectl -n elglide create secret docker-registry elglide-registry \
     --docker-server=REGISTRY --docker-username=AWS --docker-password=<token>

2. Apply the manifests (provided by Elglide): a Deployment + Service for the Gateway, a Deployment + Service for each connector you use, and the Agent Deployment:

   env:
     - name: Agent__BrokerUrl
       value: https://broker.elglide.com:8443
     - name: Agent__TenantId
       value: "<tenant id>"
     - name: Agent__AgentGroupId
       value: "1"
     - name: Agent__ConnectorManagement
       value: External                       # connectors are K8s Deployments
     - name: Agent__LocalGatewayUrl
       value: http://api-gateway:5050         # the Gateway Service
     - name: Agent__ConnectorHealthUrlByService__api-connector-sqlserver
       value: http://api-connector-sqlserver:5031

3. The Agent dials out, the Gateway routes by Service name to the connector pods. Outbound 443 only; no Ingress.

A scale-to-zero, on-demand connector mode (the Agent creating connector pods via the Kubernetes API with scoped RBAC) is on the roadmap; today, run the connectors you need as right-sized Deployments. Ask your Elglide rep for the Helm chart.

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.

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 logs.cmd 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 on Business-Critical tenants with at least one registered agent.)

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-click helpers next to the installer — no Docker knowledge needed:

Script	What it does
status.cmd	Show the agent + gateway container status.
logs.cmd	Follow the agent's live log (Ctrl+C to stop).
stop.cmd / start.cmd	Pause and resume the agent (containers kept; a stopped agent stays stopped across reboots). The Agents page badge flips to Not connected / Connected accordingly.
update.cmd	Pull the latest images and restart. If the pull hits 403 Forbidden (the bundled token lives ~12h), download a fresh install package, extract it over the folder, and run install.cmd — it updates with a fresh token.
uninstall.cmd	Stop and remove the containers (your config + certificate stay in the folder). Also deactivate the agent on the Agents page.

Linux/macOS: the package includes agent.sh with the same actions (./agent.sh status|logs|stop|start|update|uninstall).

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:

1. 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).
2. Extract the zip over the existing folder on the agent host.
3. Run install.cmd (or ./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 — uninstall.cmd 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	Agent → your source database	Reads the source on your LAN.
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.

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 Business-Critical tenants and connections you explicitly assign to an agent group — nothing else is affected.