Offline-first trail running for Android & iOS — download the map before you lose signal, follow your route with live GPS, and record every run. No account, no tracking.
An open-source app by Bernoulli Software.
RunTiyul is an offline-first Flutter application for trail route management, on-route navigation, GPS activity recording, and offline map storage. It is designed for the backcountry: everything you need works with the phone in airplane mode, and nothing about your runs leaves your device.
Current status: functional Android-verified MVP. Production map-provider configuration, iOS runtime validation, and physical-device background tracking remain before full release readiness. See the implementation status for the evidence-based, dated inventory.
- 📍 Offline maps — download map areas ahead of time and render them with no connectivity (airplane-mode capable).
- 🗺️ GPX import & route builder — bring in existing routes or build new ones by tapping real trails.
- 🏃 GPS activity recording — track distance, pace, and elevation with filtering for clean stats.
- 🧭 On-route navigation — follow your line with off-route and junction alerts so you stay found.
- 📚 Activity history & GPX export — review past runs and export them as GPX.
- 🔒 Privacy-first — local-only storage, no account, no ads, no trackers.
Public, permanent builds are published as GitHub Release assets, and the same links are surfaced on the website:
| Platform | File | Link |
|---|---|---|
| Android | RunTiyul.apk |
Download APK |
| iOS (unsigned) | RunTiyul.ipa |
Download IPA |
Android: enable "install unknown apps" for your browser/file manager, then
open the .apk (or adb install RunTiyul.apk). When moving from v1.2.0 or
older to v1.2.2 or any later permanent-key release, uninstall the old build
first; Android normally removes that installation's local data. Releases after
the v1.2.2 baseline can update in place when they retain the permanent signing
identity.
iOS: the .ipa is unsigned. Sideload it with
AltStore or Sideloadly using
your own Apple ID, then trust the developer profile in
Settings → General → VPN & Device Management.
Download links resolve once the first
v*release has been published by CI.
Prerequisites:
- Flutter stable (Dart SDK
^3.12.2), Flutter 3.44.6 or a compatible newer stable release - Android Studio and an Android emulator, or a connected Android device
- macOS with Xcode for iOS builds
flutter pub get
flutter analyze
flutter test
flutter devices
flutter run -d <device-id>This repository contains Android and iOS targets. It does not contain a Windows desktop target. For toolchain setup, VS Code debugging, GPS simulation, and offline verification, see the local run and debug guide.
# Android development build
flutter build apk --debug
# Android public release (requires the four protected signing environment values)
flutter build apk --release
# iOS (unsigned .app, then zip into an .ipa Payload)
flutter build ios --release --no-codesignAndroid release builds deliberately fail when signing credentials are absent. The credential names, pinned public fingerprint, backup requirement, and CI procedure are in the release runbook.
Two GitHub Actions workflows power distribution:
.github/workflows/release.yml— on a pushedv*tag (or manual dispatch) it builds the Android APK on Ubuntu and an unsigned iOS.ipaon macOS, then publishes a GitHub Release with the stable assetsRunTiyul.apkandRunTiyul.ipa. The tag must matchpubspec.yamland have authored notes atdocs/wiki/releases/<tag>.md..github/workflows/pages.yml— on pushes tomainthat touchsite/**(or manual dispatch) it deploys the marketing site insite/to GitHub Pages.
-
Enable Pages: repository Settings → Pages → Build and deployment → Source: GitHub Actions.
-
Publish a release after following the wiki's release-note contract:
git tag v1.2.2 git push origin main git push origin v1.2.2
The stable asset names (`RunTiyul.apk` / `RunTiyul.ipa`) keep the
`releases/latest/download/...` links valid across every future release.
## Project layout
| Path | Purpose |
| --- | --- |
| `lib/` | Flutter application source |
| `test/` | Automated tests |
| `site/` | GitHub Pages marketing/landing site |
| `.github/workflows/` | Release + Pages CI |
| `docs/wiki/` | Authoritative project wiki (start at `INDEX.md`) |
## Project wiki
Start with the [wiki index](docs/wiki/INDEX.md). It records the required reading
order, current implementation state, immediate priorities, and maintenance
rules. Release and distribution specifics live in
[Release & distribution](docs/wiki/07-release-and-distribution.md).
All coding agents must follow [`AGENTS.md`](AGENTS.md) and update the relevant
wiki pages plus the index whenever project status or documentation changes.
## Contributing & maintainers
RunTiyul is open source and **actively looking for maintainers and
contributors**. Whether you want to fix a bug, improve the docs, verify iOS, or
help steward the project long-term — you're welcome here.
**New here and want to help maintain RunTiyul?** The easiest first step is to
[open an issue or leave a comment](https://github.com/nachem/runTiyul/issues/new?title=I%27d%20like%20to%20help%20maintain%20RunTiyul&body=Hi%20Bernoulli%20Software%2C%20I%27d%20like%20to%20contribute%2Fbecome%20a%20maintainer.%20Here%27s%20a%20bit%20about%20me%3A)
introducing yourself and asking to become a maintainer.
Ways to contribute:
1. **Report bugs & request features** on the
[issues page](https://github.com/nachem/runTiyul/issues).
2. **Open a pull request** — fork, branch, run `flutter analyze` and
`flutter test`, then submit.
3. **Improve the wiki** under `docs/wiki/` following [`AGENTS.md`](AGENTS.md).
Please keep the project's principles intact: offline-first behavior, explicit
error handling, type safety, location privacy, and map-provider licensing
(never use the public `tile.openstreetmap.org` service for bulk/offline
downloads).
## License
Released under the [MIT License](LICENSE).
Map data © OpenStreetMap contributors.
---
<div align="center">
Made with 🦊 by **Bernoulli Software**
</div>