daywater

GameCube reverse engineering, simplified

Demo · Website

A self-hosted platform that connects Ghidra, Dolphin, and an LLM to reverse engineer GameCube games, understand their codebases and produce Gecko codes. Runs in a single docker container so no need to manually install any tooling. Deploy it on a server and you can do RE from anywhere! ## Quick Start (Docker) # Pull and run the pre-built image docker run -d --name daywater \ --init --shm-size=2g --cap-add=SYS_PTRACE \ -p 7860:7860 -p 7575:7575 \ -v daywater-sessions:/app/sessions \ -v daywater-cache:/app/cache \ -v daywater-logs:/app/logs \ ghcr.io/maukwm/daywater:latest Or clone and build from source: git clone https://github.com/MaukWM/daywater.git cd daywater docker compose up --build -d Open `http://localhost:7860`. On first launch, a setup wizard walks you through: 1. **API key + model** — configure your LLM backend (default: `openai/gpt-5.5`) (Note: Only OpenAI is supported for now, extensive support coming soon) 2. **Ghidra initialization** — warms the JVM and verifies the analysis engine After setup: upload an ISO, upload a savestate, create a task, run the agent. - **Web UI:** `http://localhost:7860` - **Inspect AI viewer:** `http://localhost:7575` — detailed agent traces **Requirements:** Docker, 8 GB+ RAM (16 GB recommended), `--shm-size=2g` (set in compose). ## 3 task types Daywater has a **unified task system** with three goal types: - **Find code patch** — write Gecko cheat codes (HUD removal, noclip, etc.) - **Find RAM address** — locate memory addresses (health, position, ammo) - **Static research** — explore and document game internals Each task is independently configured with **capabilities** (static RE, Gecko injection, RAM poke, input injection, frame capture, pixel diff), evaluation method, budget, and input-mutation hints. Presets are available for common workflows. ### Agent Tools | Tool | What it does | |------|-------------| | `decompile` | C-like pseudocode for any function | | `find_string` | Regex search over binary string literals | | `find_writers` | GDB watchpoints to find what writes to an address | | `read_memory` | Read live game RAM | | `make_c2_hook` | Assemble PowerPC and inject C2 Gecko hooks | | `apply_gecko_code` | Hot-reload Gecko codes into the running game | | `press_button` / `set_stick` | Full controller input — buttons, D-pad, analog sticks | | `capture_screenshot` | Grab the current frame from Dolphin | | `scan_memory` | Differential memory scanning — find what changed between two moments | | `rename_function` | Persistently annotate functions — names carry across tasks | ### Key Features ## Architecture src/ api/ # FastAPI backend, SSE events, routes agent/ # Inspect AI task, prompts, tools, scorers, job spec system core/ dolphin/ # Dolphin runner, frame capture, memory tools, Gecko injection ghidra/ # PyGhidra analysis, ISO parsing, binary cache knowledge/ # Findings, research docs, gecko code storage The agent runs via [Inspect AI](https://inspect.ai). Ghidra runs in-process via [PyGhidra](https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/PyGhidra) (no subprocess). Dolphin runs headless via `dolphin-emu-nogui`. ## Local Dev ### Nix flake nix develop # shell with Dolphin, Ghidra, Python 3.13, uv uv sync ### Manual Install Dolphin, Python 3.13+, uv, and [Ghidra 12.0.4+](https://github.com/NationalSecurityAgency/ghidra/releases/tag/Ghidra_12.0.4_build), then: uv sync export DAYWATER_GHIDRA_HOME=/path/to/ghidra ### Savestates Savestates must be created with **[Dolphin 2603a](https://dolphin-emu.org/download/release/2603a/)** (the build in the container and nix flake). They are not portable across Dolphin versions AFAIK. 1. Boot the game in Dolphin GUI 2. Play to an in-game scene 3. Save state (Shift+F1) 4. Upload via the web UI On Wayland, wrap Dolphin with gamescope: `gamescope -w 800 -h 600 -- dolphin-emu /path/to/game.iso` ## Dev Commands uv run pre-commit run --all-files uv run pytest ## Docker Notes - `init: true` in compose for zombie reaping (Dolphin child processes) - `cap_add: SYS_PTRACE` for memory debugging tools - `shm_size: 2g` required (Dolphin MemArena exceeds default 64 MB `/dev/shm`) - Ghidra SLEIGH specs are pre-compiled in the image including GameCubeLoader's Gekko/Broadway language - The entrypoint fixes bind-mount permissions automatically on fresh deploys ## AI Development Disclosure Yes, AI was heavily employed in the creation of this project. Shoutouts to claude for figuring out how to get ghidra and dolphin work in docker containers. Special gratitude for all the frontend work. ## License [AGPL-3.0](LICENSE)