Instancer

The instancer gives each team an isolated copy of a challenge service running on Docker or Kubernetes. Participants can start, inspect, extend, and stop their instance through rCTF.

Instanced challenges work well when teams need private mutable state, a dedicated service process, or a target that should disappear after a timeout.

Pick a backend

Both providers give participants the same controls and use the same shared challenge fields, but each backend has its own deployment guide.

• Docker instancer is a bundled Python FastAPI service driving Docker, Traefik, and Redis.
• Kubernetes instancer is a Go operator driving GKE, Traefik, and Terraform.

How it works

Each challenge uses instancerConfig to select a named instancer and set its ID, timeout, public endpoints, and provider-specific settings. If the challenge does not select one, rCTF uses defaultInstancer or the only configured instancer.

When a participant starts an instance, rCTF validates the challenge configuration and sends the request to Docker or Kubernetes. The challenge page shows the instance status and the endpoints in the order listed under expose, along with controls to extend or stop it.

Provider configuration

Define instancers under the instancers map in rctf.d/. Each key is a name you choose, and challenges use that name to select an instancer. defaultInstancer chooses the fallback for challenges that don’t specify one. It is required when you configure more than one instancer. With only one, rCTF selects it automatically.

1
instancers:
2
  docker:
3
    name: instancers/docker
4
    options:
5
      apiUrl: http://tiny-instancer:1337
6
      authToken: <shared-secret>
7
  k8s:
8
    name: instancers/k8s
9
    options:
10
      apiUrl: https://k8s.example.com
11
      authToken: <service-account-token>
12
      caCertificate: |
13
        -----BEGIN CERTIFICATE-----
14
        ...
15
        -----END CERTIFICATE-----
16
defaultInstancer: docker

A single-instancer deployment only needs one entry, and defaultInstancer can be omitted:

1
instancers:
2
  docker:
3
    name: instancers/docker
4
    options:
5
      apiUrl: http://tiny-instancer:1337
6
      authToken: <shared-secret>

Challenge configuration

Each instanced challenge needs instancerConfig. Its ID, timeout, extension setting, and exposed endpoints work the same with either provider. The contents of config depend on whether the challenge uses Docker or Kubernetes.

1
instancerConfig:
2
  challengeIntegrationId: web-demo
3
  instancer: docker
4
  timeoutMilliseconds: 600000
5
  extendable: true
6
  config:
7
    # Provider-specific config.
8
  expose:
9
    - kind: https
10
      hostPrefix: web-demo
11
      containerName: app
12
      containerPort: 8080
13
      shouldDisplay: true
14
      title: Challenge

The expose entries map public endpoints to a service container or pod:

Endpoint kinds

Endpoint support is provider-specific:

Participant actions and API routes

The instance routes are under /api/v2/integrations/challs/:id/instance:

The returned status is stopped, starting, running, stopping, or errored.

Captcha can protect create and extend actions:

1
captcha:
2
  protectedEndpoints:
3
    - instancerStart
4
    - instancerExtend

Provider schemas and the admin UI

The fields shared by both providers remain the same. Only config differs. Docker accepts a Compose-like service definition, while Kubernetes accepts pods[]. Each provider publishes a JSON Schema that describes and validates its version of config.

The schema endpoint returns the schema for each configured instancer and identifies the default. Deployment tools can use the same endpoint to validate a challenge before sending it to rCTF.

Dynamic admin UI

The challenge editor builds its form from these schemas. If several instancers are configured, selecting one updates the available fields and validation rules. Use the advanced YAML editor when a setting cannot be represented by the generated form.