README.md

metadata

title: KERNEL-95 - The Last Desktop
emoji: 🖥️
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: true
tags:
  - track:wood
  - sponsor:openai
  - sponsor:modal
  - achievement:offbrand
  - achievement:tiny

KERNEL-95: The Last Desktop

In 2077, you join the KERNEL-95 Recovery Division to investigate Device 013: an obsolete computer recovered from a sealed MetroGrid Behavioral Lab archive. It has no power source, yet it is still running. Three technicians who touched it each lost exactly thirteen minutes of memory.

To enter the machine, you connect MIRROR.exe, your assigned forensic AI assistant. Inside a corrupted retro desktop, you open files, recover deleted messages, compare restore points, run contradiction scans, and search for ECHO: an unknown intelligence hiding inside the system.

But MIRROR is not a neutral assistant. She diverts your questions, suppresses evidence, and rewrites her own testimony because she is secretly protecting ECHO.

KERNEL-95 is an AI-native forensic game where the model performs MIRROR's evasions, ECHO's fragmented confessions, and the emotional tension between them, while a deterministic investigation engine protects the actual truth.

At the end of Case 013, you decide whether to delete ECHO, extract him, expose MIRROR, protect them both, or allow something impossible to survive inside the last desktop.

The exact player guide is in HOW_TO_PLAY.md.

Social Post + Demo Video

Watch the KERNEL-95 demo and read the social post: x.com/praedico/status/2065889011139215517

OpenAI Codex Track

Public source repository: github.com/0xPraedico/KERNEL-95

KERNEL-95 was developed with OpenAI Codex as the coding agent. Codex-attributed commits include the Co-authored-by: OpenAI Codex <codex@openai.com> trailer in the public Git history.

Core Game

• A movable late-1990s desktop inside a CRT.
• A large pink MIRROR terminal for commands and conversation.
• Clickable files, deleted evidence, restore points, and a hidden partition.
• Deterministic Python tools own facts, unlocks, progression, and endings.
• MIRROR and ECHO can use an optional OpenAI-compatible model for voice.
• The full game works without a model or API key.
• The World Cup shortcut uses live fixtures with browser-local mock predictions. It has no account or remote persistence.

Quick Demo

1. Click CONNECT MIRROR.exe.
2. Open CASE_013_BRIEFING.txt.
3. Ask MIRROR about ECHO.
4. Recover echo_letter_01.tmp from the Recycle Bin.
5. Challenge MIRROR once and run one contradiction scan.
6. Compare restore points or run verify mirror.
7. Run audit mirror, then unlock hidden_partition.
8. Inspect ECHO's files and submit the Final Judgment.

Useful terminal commands:

help
status
dir
type CASE_013_BRIEFING.txt
recover echo_letter_01.tmp
run contradiction_scan
trace echo
compare restore_points
verify mirror
audit mirror
unlock hidden_partition
listen echo

Local Run

Python 3.10 or newer is required.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Open http://127.0.0.1:7860.

Verification:

python -m compileall .
python smoke_test.py
ruff check app.py neon_trace smoke_test.py

Hugging Face Space

The default deployment is a standard CPU Gradio Space. It does not require a GPU, Modal, or an API key.

1. Create a new Hugging Face Space with the Gradio SDK.
2. Push this repository to the Space.
3. Set these Space variables:

GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=7860

4. Leave the following secrets empty for deterministic fallback mode:

OPENAI_API_KEY=
OPENAI_BASE_URL=
OPENAI_MODEL=

The app launches and remains fully playable when OPENAI_API_KEY is absent. If a configured model endpoint fails or times out, narration automatically returns to authored deterministic responses. Model output cannot create evidence, change unlocks, or select an ending.

Modal vLLM backend

The Hugging Face Space runs the KERNEL-95 game UI. Modal runs Qwen/Qwen3-4B-Instruct-2507 behind vLLM's OpenAI-compatible API. The model only supplies MIRROR/ECHO voice; deterministic tools remain authoritative and model output cannot mutate GameState.

Create a local environment:

conda create -n kernel95-modal python=3.11 -y
conda activate kernel95-modal
python -m pip install "modal>=1.0.0" openai
python -m modal setup

Create the Modal secret used by modal_vllm.py. Choose a private API key and reuse exactly the same value in the Hugging Face Space:

export KERNEL95_MODAL_API_KEY="replace-with-a-long-random-value"
modal secret create kernel95-modal-api-key \
  KERNEL95_MODAL_API_KEY="$KERNEL95_MODAL_API_KEY"

Deploy the vLLM server:

modal deploy modal_vllm.py

Modal returns an HTTPS endpoint after deployment. Use its /v1 path as the OpenAI base URL:

https://<modal-endpoint>/v1

Set these Hugging Face Space secrets:

OPENAI_API_KEY=<same api key used by Modal>
OPENAI_BASE_URL=https://<modal-endpoint>/v1
OPENAI_MODEL=Qwen/Qwen3-4B-Instruct-2507

Test the deployed endpoint with the same variables in your local shell:

python test_modal_endpoint.py

The Modal deployment keeps one L4 container warm, uses a persistent kernel95-hf-cache volume, and caps the deployment at one replica. This avoids the normal scale-to-zero delay for the first MIRROR message. At Modal's published L4 rate of $0.000222/second, seven continuously warm days cost about $134.27 for the GPU, plus CPU and memory. If Modal fails or restarts, KERNEL-95 falls back to deterministic authored responses and remains fully playable without OPENAI_API_KEY.

Why the AI is load-bearing

MIRROR is the unreliable witness; KERNEL-95 is the truth engine. For every free-form question, deterministic case state secretly selects one performance tactic: contradiction, diversion, or admission. Qwen performs that tactic using the player's wording and recurring motifs. The player then classifies the answer, and deterministic evidence decides whether the accusation is correct.

The model never receives authority to create evidence, unlock files, mutate GameState, or choose an ending. It also does not narrate technical results. Responses containing invented paths, filenames, timestamps, metrics, or command results are discarded and replaced by the authored fallback.

Model evaluation

modal_voice_eval.py runs the same 20 MIRROR prompts against a deployed model. The selected 4B deployment had a roughly 97-second first cold start and generally answered in 0.6-1.6 seconds warm.

The evaluation showed that generated technical reporting could invent details. The final design therefore narrows the model's job to subjective roleplay while the deterministic UI owns every fact. Under that voice-only protocol, Qwen/Qwen3-4B-Instruct-2507 retained the eerie MIRROR performance with much lower warm latency, so it is the selected model.

Run the repeatable 20-dialogue MIRROR voice suite without copying the API key out of the Modal secret:

modal run modal_voice_eval.py \
  --base-url https://<modal-endpoint> \
  --model Qwen/Qwen3-4B-Instruct-2507 \
  --output mirror_voice_eval_4b.json

Optional Debug Easter Eggs

Debug-only prototype shortcuts, including Tetris, are hidden from normal players and demos. They can be restored only for local development:

KERNEL95_DEBUG_EASTER_EGGS=1 python app.py

Project Layout

app.py
neon_trace/
  game_state.py
  os_data.py
  os_actions.py
  os_tools.py
  os_desktop.py
  ai_engine.py
  styles.py
smoke_test.py
HOW_TO_PLAY.md