Runners

A runner is a small process you run inside your own network that connects out to SemiLayer and executes database queries on our behalf. It dials out; we never dial in. Credentials — if you want — stay entirely on your side.

When you want one

• Your database sits behind a corporate firewall that won't allowlist external IPs on principle.
• Your security team requires all database credentials stay on your equipment — even in encrypted form on our side.
• You're in a fully air-gapped environment and SemiLayer is only allowed outbound HTTPS.

How it works

Your network                       │  SemiLayer
                                   │
┌───────────────────────────┐      │   ┌──────────────────────┐
│ semilayer-runner          │──────┼─→ │ runner.semilayer.com │
│ (Docker or node CLI)      │ wss  │   │ (runner gateway)     │
│ reads your local DB       │      │   │                      │
└────────┬──────────────────┘      │   └─────┬────────────────┘
         │                         │         │
    ┌────▼──────┐                  │         │ dispatches jobs from
    │ Postgres  │                  │         │ the api.semilayer.com
    │ / MySQL   │                  │         │ service
    │ / etc     │                  │         │
    └───────────┘                  │   ┌─────▼────────────────┐
                                   │   │ api.semilayer.com    │
                                   │   │ (service + worker)   │
                                   │   └──────────────────────┘

• A runner maintains one outbound WebSocket connection to wss://runner.semilayer.com/connect.
• When a query routes to a source that has runner assignments, the gateway dispatches the job over the open socket. The runner opens (or reuses) the database connection, executes, and streams results back.
• Every query still goes through api.semilayer.com first — RBAC, rate limiting, billing, and access rules all run there before any runner sees the request.

Next

• Install a runner — Docker one-liner or the semilayer-runner CLI from npm.
• Assign sources — which sources use runners and which use direct (SaaS) egress.
• Multiple runners — run N runners for redundancy and load balancing. Dedup is safe.
• Security boundaries — what leaves your network, what stays.
• Airgap mode — keeping credentials entirely off SemiLayer's side.
• Troubleshooting — doctor command and common issues.

Source & artifacts

• Docker image — ghcr.io/semilayer/runner (public). Pin to a version in production.
• npm package — @semilayer/runner-cli. Same bits; the image just wraps this.
• Public repo — github.com/semilayer/runner. Docs, security policy, issue tracker.