Customer-Hosted BYOC VPC Runners Guide

Customer-Hosted (BYOC) Runners & On-Premises Deployment Guide

CertiQA supports two enterprise execution models for strict security, compliance and private-network requirements. Both are part of the enterprise offering; contact [email protected] to enable them for your organization.

Hybrid SaaS / BYOC runners: CertiQA Cloud stays your control plane while test execution runs inside your own network.
Full on-premises deployment: the control plane, data plane and database run in your environment.

1. Customer-Hosted (BYOC) Runners

 ┌─────────────────────────────────────────────────────────────┐
 │                CERTIQA CLOUD (control plane)                │
 └─────────────────────────────▲───────────────────────────────┘
                               │
            Outbound HTTPS     │  no inbound ports required
            (port 443)         │  registration, heartbeat, job polling,
                               │  results and screenshots
 ┌─────────────────────────────▼───────────────────────────────┐
 │                 YOUR NETWORK / VPC                          │
 │   ┌──────────────────────────────────────────────────────┐  │
 │   │ CertiQA runner                                       │  │
 │   │ • Executes Playwright against internal apps          │  │
 │   │ • Reaches e.g. http://staging.internal.corp:8080     │  │
 │   └──────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────┘

Why outbound-only matters

No inbound firewall openings. The runner starts every connection, so your security team does not open public ports or allow-list static IPs.
Access to private environments. Run suites against internal apps and staging environments that are not reachable from the internet.
Test data stays in your network. Test credentials, internal data and the pages under test are handled by the runner inside your network during execution; results and screenshots are sent back to your CertiQA project.

2. Deploying a Runner

CertiQA gives BYOC customers access to the runner image (from a private registry) and a runner token. The runner is configured with environment variables:

Variable	Purpose
`CERTIQA_API_URL`	The CertiQA API, e.g. `https://api.certiqa.app`
`CERTIQA_RUNNER_TOKEN`	Runner token issued for your organization (store it as a secret)
`CERTIQA_RUNNER_NAME`	A name for this runner, shown in the console
`CERTIQA_RUNNER_TAGS`	Comma-separated tags used to route runs to matching runners
`CERTIQA_POLL_INTERVAL_MS`	Optional: how often the runner polls for jobs
`CERTIQA_HEALTH_PORT`	Optional: port for the runner’s local health endpoint

docker run -d --name certiqa-runner \
  --restart unless-stopped \
  -e CERTIQA_API_URL="https://api.certiqa.app" \
  -e CERTIQA_RUNNER_TOKEN="<runner token>" \
  -e CERTIQA_RUNNER_NAME="aws-us-east-1-worker-01" \
  -e CERTIQA_RUNNER_TAGS="aws,staging,internal-vpc" \
  <registry-provided runner image>

The same image and variables run as a Docker container, an ECS task or a Kubernetes Deployment; only outbound HTTPS to the CertiQA API is required. If your network inspects TLS with its own CA, mount the CA certificate and set NODE_EXTRA_CA_CERTS.

3. Runner Health

A runner reports as ONLINE, BUSY or OFFLINE.
Runners send heartbeats; a runner silent for more than 45 seconds is marked OFFLINE.
Tag suites or runs with a runner tag so jobs go only to matching runners.

4. Full On-Premises Deployment

For organizations that need the whole platform inside their own environment, CertiQA provides the deployment package (Docker Compose files and a Helm chart) with the enterprise on-premises license. Contact [email protected].

On-premises installs run in an enterprise license mode: credit balance checks are disabled (CERTIQA_UNLIMITED_CREDITS=true) and usage analytics continue to be recorded for internal reporting.

AI features on-premises

CertiQA’s cloud-hosted AI is not available to an on-premises install. AI features (CertiMind authoring, smart triage, LLM-as-a-Judge) need your own model access, configured with Bring Your Own Key (BYOK) in the tenant settings. Which providers and private endpoints are supported for your deployment is confirmed with CertiQA when you enable the on-premises package.