Runner · In-situ execution · Custodian-controlled
The query travels. The data stays.
Runner is the in-situ execution engine that lives inside the custodian's boundary. It receives UQL queries, compiles them to local SQL, returns aggregate-only results, and logs every step. No patient-level data ever crosses the wall.
DEPLOYMENT TOPOLOGY
UNISON CONTROL PLANE
Dispatcher
· UQL artefact
· signed · versioned
· authored by researcher
→ UQL query━━━
CUSTODIAN BOUNDARY
RUNNER · IN-SITU
Execution engine
· verify signature
· compile UQL → SQL
· execute locally
· aggregate-only
· small-cell suppress
· sign result
data · OMOP CDM · custodian VPC · never leaves
← aggregates━━━+ signed result
RESEARCHER
Results view
· counts · curves
· distributions
· replayable artefact
Query in, aggregates out. Nothing else crosses the boundary.
01 · What Runner is
A small, hardened service. Runs inside your walls. Answers to you.
WHAT IT IS NOT
- Not a data pipe to a remote cloud.
- Not a copy of your data held by Unison.
- Not an agent with free-form access to your warehouse.
- Not a push-based integration you can't audit.
WHAT IT IS
- A stateless execution service that lives inside your VPC or on-prem.
- Receives UQL queries via authenticated API. Compiles. Executes. Returns aggregates.
- Inspected, logged and controlled by your team — not ours.
- Pull-based by default: nothing happens without an artefact you accept.
02 · Capabilities
Six things Runner does. That's the whole list.
01 · RECEIVE
Authenticated artefact ingestion
Runner authenticates with the Unison API via token. Incoming UQL artefacts are validated against the local OMOP schema before execution.
02 · COMPILE
UQL → local SQL
Compiles UQL against the local SQL instance into a virtual OMOP / CDISC / Sentinel CDM layer. Deterministic, inspectable. The SQL is logged.
03 · EXECUTE
In-situ query execution
Runs inside the custodian's warehouse — PostgreSQL, MySQL, SQL Server, Spark. Uses the credentials your team grants, nothing else.
04 · AGGREGATE
Small-cell & privacy layer
Small-cell suppression (minimum count thresholds) applied before anything returns. Configurable per custodian policy.
05 · RETURN
Aggregate result
Only aggregate counts cross the boundary. Results are returned via the API with full execution metadata for reproducibility.
06 · LOG
Full execution audit
Every artefact received, every query run, every result returned — logged to a store you own. Pipe it to your SIEM.
03 · Deployment
However your infra team prefers to run it.
01
Docker
Single-container deployment. Pull the image, set two environment variables, run. The fastest path from zero to a connected runner.
02
Singularity
For HPC clusters and regulated environments where Docker is not permitted. Same image, same behaviour.
03
Kubernetes
Horizontal scaling, pod-level RBAC. Most common choice for hospital networks and research clouds.
QUICK START · DOCKER
$ docker run --rm -ti \
--env UNISON_API_TOKEN=xxx \
--env UNISON_DSN="postgresql+psycopg2://user:pass@host:port/db" \
entsupml/unison-runner:0.4.8
# Runner is now live and connected to your OMOP database.
04 · SECURITY POSTURE
Built so the default answer to "can it leak?" is structurally, no.
Runner has no outbound path for patient-level data. Its only egress is the aggregate result. Reviewed, penetration-tested, and independently assessable — the whitepaper is available on request.
CONTROLS
Ingresspull-based · authenticated artefacts only
Egressaggregate results · no row-level data
Identitycustodian-issued service account
Secretsyour vault · your rotation
Auditfull log · streams to your SIEM
Disconnectrevoke API token · runner goes offline
AssuranceCE+ · pentest report
05 · Observability
Your team sees everything, before anyone else does.
Queue of pending artefacts
A dashboard of every incoming UQL artefact: author, protocol, biobank target. Review query details before execution.
Query inspector
Every compiled SQL is available for pre-execution review. Approve individually, or auto-approve within policy.
Result ledger
Every returned aggregate, signed and searchable. Filter by protocol, date, researcher or sponsor. Export for audit.
Standards & fit:· Cyber Essentials Plus· GxP-deployable· EHDS-aligned· FHIR-aware· OMOP CDM-native
06 · Who runs Runner
The custodian stays the custodian.
HOSPITAL NETWORKS
Inside the clinical-data boundary
Runner deploys to your research environment. Your IT team owns credentials, logs, policy. Nothing changes hands.
BIOBANKS & REGISTRIES
Beside the consented data
Consented-cohort governance stays intact. Queries run against exactly the data participants consented to.
NATIONAL DATA BODIES
Aligned to sovereignty posture
Regional data never leaves the region. Runner is operable under national data-sovereignty regimes.
Runner SDK · deployment guide · security whitepaper