Submission Guide

How to set up, test and submit a solution for GKÍ 2027.

Using Claude Code, Codex or another coding agent? The starter's AGENTS.md gives it the context it needs. A team member still approves each score: submitting needs a passkey on a team member's account on this website.

What you need

Python 3.11 or newer, and git.
A free ngrok account for a public address (recommended), or cloudflared for connect.
A device that supports passkeys: Face ID, Touch ID, Windows Hello or a security key.
An account on this website and a place in a 2027 team.

Get the starter

The 2027 starter repository is published at kickoff. Once you have it, run:

python gki.py setup

setup creates .venv and a .env file with your own API key. Organizers never issue keys. Never commit .env or paste the key into chat. Use python3 if python is not found.

Test on your computer

python gki.py test    # unit tests
python gki.py run     # server on http://localhost:8000
python gki.py check   # in a second terminal

check sends example requests to your server with your API key. Local testing is unlimited and never touches hidden data.

Make it public

We recommend ngrok. Keep run going and start ngrok on the same port (8000) in a second terminal:

ngrok config add-authtoken <token>       # once, with the token from your ngrok dashboard
ngrok http 8000                          # prints your public https:// address; keep it open
python gki.py check https://<address>    # in a third terminal

A free ngrok account comes with one fixed address (ending in ngrok-free.app or ngrok-free.dev) that stays the same when ngrok restarts. In a browser, ngrok first shows a warning page: click Visit. The evaluator calls your server directly and does not get that page.

Alternatively, connect starts your server behind a Cloudflare quick tunnel (needs cloudflared). Stop run first, because connect starts the server itself on port 8000:

python gki.py connect                     # prints the public address and API key; keep it open
python gki.py check https://<address>     # in a second terminal

The trycloudflare.com address changes each time connect starts. Any public HTTPS host also works: your own server or cloud service, or Docker behind HTTPS.

Submit on the website

Sign in and join a 2027 team.
Set up a passkey for your device on the submission page. You confirm your password first (or a code we email you, if you sign in with Google).
Choose the challenge and Validation, paste the base address and API key, and confirm with your passkey.

Enter only the base address: https:// and the host name, with no path (not …/predict), no port other than 443, and no ?, #, user name or password. Private and local addresses are not allowed.

A team member takes this step. The passkey confirms that a team member's account approved the score; it does not prove who wrote the solution. Coding agents can prepare the address and key, but a team member submits.

Keep the server running until the score is finished.

Rules that affect your plan

Validation has a daily limit per team and challenge. The submission page shows how many are left; the count resets at 00:00 UTC.
Failures caused by the website or the evaluator do not count against the limit.
Each team can have one queued or running score per challenge.
The final test is one attempt per team and challenge. A started run uses the attempt; a run the evaluator refuses before contacting your server does not.
Final-test scores stay hidden until results are published.
Your server is never told whether a request is for validation or the final test.

Troubleshooting

The website cannot reach my server: localhost is not public. Use ngrok, connect or a hosted server, and open <address>/health from another network, such as a phone with Wi-Fi off.
The address is rejected: Enter only the base https:// address on port 443, with no path, ?, #, user name or password. Private and local addresses are not allowed. If the host name cannot be found, the form says so: check the address and that ngrok or connect is still running.
401 Invalid API key: Paste the exact key from .env or the connect output, without quotes or the word Bearer.
422 error: The request does not match the API contract. Run python gki.py test and compare with the example requests in fixtures/.
500 error: Your code raised an error, returned the wrong number of answers or an invalid output. Check the terminal where the server runs.
Timeout or the tunnel dropped: Keep the computer awake, load the model at startup rather than on each request, and answer within the problem's time limit.
A score is stuck or failed on our side: Keep the submission ID and contact an organizer on Discord. Organizers can restore a final-test attempt after a verified infrastructure failure.
Before the final test: Run validation first and use a host that stays up for the whole evaluation. A tunnel stops when ngrok or connect stops, and ngrok's free plan has monthly request and data limits.

Questions and answers

Technical FAQ

What is a model?

A model is a system that produces outputs from inputs, such as a large language model like ChatGPT or a simple linear function. Most models are trained on pairs of inputs and expected outputs. Training minimizes a loss function so the model's predictions come as close to the expected outputs as possible.

How is model performance measured?

With a scoring metric computed on data the model has not seen. Accuracy, the share of correct predictions, is the most common. Others include MSE, F1 score and AUC. Each problem's metric is published with the problem.

What is an API, and why does the competition use one?

An API (application programming interface) is an agreed way for programs to exchange requests and responses, usually JSON over HTTPS. Your server provides one; the evaluator sends it hidden inputs and scores the answers. The starter already implements the API, so you write the model code.

What is the API key?

A secret the evaluator sends with every request, so your server knows the request is genuine. python gki.py setup generates it; organizers never issue keys. It is stored in .env. Never commit it or paste it into chat, and enter it only on the submission page.

Why can't I just upload my model?

Teams use different languages, libraries and hardware, and running all of it on our side would be slow and fragile. With an API, the evaluator only needs your address and key, and you keep full control of your code. This is also how models are usually served in industry.

What is a tunnel, and what does gki.py connect do?

A tunnel gives a server on your computer a public HTTPS address without changing your router settings. We recommend ngrok: ngrok http 8000 forwards your fixed ngrok address to the server that run starts. Alternatively, connect starts your server and a Cloudflare quick tunnel through cloudflared, then prints the address and key. That address works only while connect runs and changes each time it starts.

Can I run the server on my laptop?

Yes. Keep it awake, plugged in and online until the score finishes. For the final test, use a host that will stay up for the whole evaluation.

Why must the address be public HTTPS?

The evaluator runs in the cloud, so it cannot reach localhost or a private network. HTTPS encrypts your key and answers in transit. The form accepts only the base address on port 443; the evaluator adds the API paths itself.

What does the passkey step do?

Every score must be approved with a passkey on a team member's account on this website, for that problem, dataset, address and key. It confirms that a team member's account approved the score; it does not prove who wrote the solution. The step is deliberately manual: your coding agent can prepare the address and key, and a team member submits.

What counts against the daily validation limit?

Every validation submission your team starts for that problem, including ones still queued or running. Failures caused by the website or the evaluator do not count. The submission page shows how many are left, and the count resets at 00:00 UTC.