Quickstart

This walks through launching a working demo challenge. It uses a public nginx image that runs cleanly under KIMO's pod hardening, so it works on any cluster with internet access.

1. Create a challenge template

kubectl apply -f config/samples/kimo_v1alpha1_challengetemplate.yaml

This creates a flag Secret and a ChallengeTemplate named demo-web. The template controller validates it (flag secret exists, image set) and marks it ready:

kubectl get challengetemplates
# NAME       ...
# demo-web
kubectl get challengetemplate demo-web -o jsonpath='{.status.ready}'
# true

The template must be Ready before instances start

An instance of a template that isn't Ready stays in Pending. The most common cause is a missing flag secret — check kubectl get challengetemplate <name> -o jsonpath='{.status.message}'.

2. Launch an instance

kubectl apply -f config/samples/kimo_v1alpha1_challengeinstance.yaml
kubectl get challengeinstances -w

The instance moves through the lifecycle as its pod comes up:

NAME                  PHASE
demo-web-team-alpha   Creating
demo-web-team-alpha   Running

Behind the scenes KIMO created, all owned by the instance:

kubectl get deploy,svc,networkfence,networkpolicy -l kimo.io/instance=demo-web-team-alpha
kubectl get deploy,svc demo-web-team-alpha

spec.templateRef and spec.team are required — an instance without them is rejected at admission time.

3. Reach the challenge

The Service exposes the template's expose: true ports inside the cluster:

kubectl port-forward svc/demo-web-team-alpha 8080:8080
curl -s localhost:8080 | head -3

4. Watch it expire

The demo template sets ttl: 1h (the instance can override it with spec.ttlOverride). Sixty seconds before expiry the instance enters Expiring and the scoring backend is notified; at expiry the instance and everything it owns — pod, service, network policy — are deleted.

To tear it down early:

kubectl delete challengeinstance demo-web-team-alpha

Using the REST API instead

Everything above can be driven over HTTP, which is how a scoring platform integrates:

kubectl port-forward svc/kimo 8080:8080 &

curl -X POST localhost:8080/api/v1/instances \
  -H "Authorization: Bearer $KIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "demo-web", "team": "team-alpha", "player": "alice"}'

See the REST API reference for all endpoints, including the proof-of-work flow for PoW-gated templates.