Gateway

The gateway is a long-lived process you run (Docker, Kubernetes, ECS, or a VM). It talks to the eltPulse control plane only over outbound HTTPS using a Bearer token from the app. It can poll for pending pipeline runs, pull connection profiles (including decrypted secrets for agent use), send heartbeats, patch run status, and evaluate monitors when you choose customer-side placement.

You do not open inbound firewall rules for eltPulse to reach your network. The gateway only egresses to your app URL and to the data sources or warehouses you configure in your jobs.

Control plane vs gateway

Directing pipelines and monitors to a gateway

A run is visible to GET /api/agent/runs when the Bearer token belongs to the same user and either the run is untargeted (targetAgentTokenId is null — any of your gateways may claim it) or the run is targeted to that named token's id. Set targeting via the pipeline default gateway, account/org defaults on Gateway, or targetAgentTokenId when creating a run through the API. Monitors use Runs on per monitor; when set to customer gateway (or inherit on a customer execution plane), the process using your token evaluates them and reports via POST /api/agent/monitors/:id/report.

Full resolution order, object relationships, and SVG diagrams (entity model + egress architecture): Concepts.

Set up in the product

1. Sign in and open Gateway (under your account / workspace).
2. Set your account execution plane to Your infrastructure when you want runs to target gateways instead of eltPulse-managed compute (you can still override per pipeline under Runs on in the builder).
3. Generate a named token (recommended) or use an org-scoped token on Pro/Team. Copy the token once — it is shown only at creation time.
4. Optionally set JSON metadata on the token, for example {"cloud":"aws","region":"us-east-1"} for your own labels. For advanced dispatch you can add pipelineRunIsolation / monitorCheckIsolation (inline or spawn) so the manifest tells a custom gateway to fork ECS/K8s jobs instead of running everything in one process.

Environment variables

Every gateway deployment needs at least:

• ELTPULSE_AGENT_TOKEN — the Bearer secret from the Gateway page (same name as in Docker samples).
• ELTPULSE_CONTROL_PLANE_URL — your app base URL, e.g. https://app.eltpulse.dev or your self-hosted origin (no trailing slash required).

Optional flags depend on the reference gateway in this repo (see below): stub run completion, monitor polling, spawn commands for isolated workers, etc. Read integrations/gateway/README.md in the source tree for the full list.

Reference gateway (this repository)

A minimal Node implementation lives at integrations/gateway/ in the eltpulsehq/integrations mirror (same layout as this monorepo). It uses the same HTTP contract as any custom agent you build.

cd integrations/gateway
npm install
export ELTPULSE_AGENT_TOKEN="…"
export ELTPULSE_CONTROL_PLANE_URL="https://your-app.example"
# Optional: stub-complete pending runs (demos only)
# export ELTPULSE_EXECUTE_RUNS=1
node src/index.mjs

Published image: ghcr.io/eltpulsehq/gateway:latest. Build locally with the included Dockerfile, or run from source as above.

docker run --rm \
  -e ELTPULSE_AGENT_TOKEN \
  -e ELTPULSE_CONTROL_PLANE_URL=https://your-app.example \
  ghcr.io/eltpulsehq/gateway:latest

Where to run it (ECS, Kubernetes, local)

The same gateway image and token work everywhere; only deployment changes. Sample manifests and Terraform live alongside the gateway in the integrations repo under paths such as gateways/docker, gateways/local, and (as they are published) ECS/Kubernetes examples — start from gateway/ and gateways/.

For production, treat the long-lived process as a dispatcher: keep polling and heartbeats in a small service, and start separate containers or jobs per pipeline run (or per monitor check) so user code cannot take down the poller. The reference gateway supports spawn isolation via env and token metadata; see the README in integrations/gateway.

HTTP API (Bearer token)

Stable routes under your app origin (all require Authorization: Bearer …):

• GET /api/agent/manifest — poll intervals, workloads (pipelines, monitors), billing hints, executorHints for named tokens.
• GET /api/agent/runs — pending (or other) runs with pipeline payload for execution.
• PATCH /api/agent/runs/:id — report status, structured logs, telemetry (rows, bytes, progress samples), and terminal state — same JSON body as PATCH /api/elt/runs/:id (session).
• GET /api/agent/connections — list connections with decrypted secret key/value pairs for the agent (use only in trusted runtime).
• POST /api/agent/heartbeat — liveness and version labels.
• POST /api/agent/monitors/:id/report — when a monitor is configured to run on the gateway, post evaluation results so the control plane updates timestamps and can enqueue a pipeline run.

Organization gateways

On Pro/Team, the org owner can create org-scoped gateway tokens. The workspace default gateway applies to unrouted runs when you work in that org context. Per-pipeline Runs on and per-run targeting still let you mix eltPulse-managed and customer gateways in one workspace.

Related

• Concepts — pipelines, runs, connections, monitors, gateway targeting.
• Runs — logs, telemetry, and how workers PATCH runs.
• Orchestration — schedules, monitors, where monitors run.
• Security & data — what we store, how connections relate to agents.
• Gateway (in-app) — generate tokens and copy env snippets.