Use self-hosted runners when test execution must stay inside your network while Certyn remains the control plane, or when your tests need tools a cloud Machine does not keep (Java, other browsers, Docker, a database).

How it works

The runner asks Certyn for work over outbound HTTPS.
It starts and stops a Docker container for each run on its host, through /var/run/docker.sock.
The live view of a run streams over an outbound websocket from the runner to Certyn.

No inbound firewall rules are required.

Prerequisites

Linux host with Docker Engine.
Outbound HTTPS access from runner host to Certyn API.
Persistent host path for runner state (/var/lib/certyn-runner recommended).
Tenant admin access in Certyn to create pools and registration tokens.

1. Create Pool and Token

In Environments > Self-hosted runners:

Create a runner pool.
Click Create token for that pool.
Copy and store the token securely (shown once).

2. Start Runner Container

Run the runner image with Docker socket and persistent state:

docker run -d \
  --name certyn-runner \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/certyn-runner:/var/lib/certyn-runner \
  -e CONTROL_PLANE_URL=https://your-certyn-api.example.com \
  -e RUNNER_POOL_ID=<POOL_ID> \
  -e REGISTRATION_TOKEN=<REGISTRATION_TOKEN> \
  -e RUNNER_NAME=runner-east-1 \
  -e MAX_CONCURRENCY=2 \
  docker.io/certyn/runner:<tag>

Production recommendation:

Use a pinned release tag (vX.Y.Z) in production.
Avoid latest for production runners to keep rollouts deterministic.

3. Configure Environment Routing

In Environments:

Set Execution target to Self-hosted runner.
Select the target Runner pool.
Save.

New runs for that environment will be scheduled to the selected pool.

Keep files between runs

Each run gets a new container, so anything installed during a run is gone after it. Give the runner a workspace folder, and every run's container sees it at /workspace. Certyn keeps your cloned repo, the tools it installs (a JDK, Maven, browsers) and the caches (npm, pip, Maven, Gradle, NuGet and Playwright's browsers) there, so the next run starts fast. See Work in Your Repo.

Add one line to the runner command:

  -e WORKSPACE_PATH=/srv/certyn-workspace \

WORKSPACE_PATH is a folder on the host (Docker creates it if it is missing) or the name of a Docker volume. The runs on this runner share it, so give each runner pool its own folder, and use it only for your own team's runs. On Linux, the runs use user id 1000; Certyn makes the folder writable for it at the start of each run.

Install tools

A run's container has Node, Python, Playwright, Chromium with chromedriver, git and the GitHub CLI, and the agent can use sudo apt-get install for anything else. Without a workspace folder, installs happen again on every run. With one, Certyn installs tools into /workspace once and reuses them.