- TypeScript 89%
- JavaScript 8.8%
- CSS 1%
- Python 0.3%
- Java 0.2%
- Other 0.6%
Fidget Beeby
5596d8cdba
All checks were successful
Build Android APK / build-apk (push) Successful in 37s
Build & Push Lite Container Image / publish (push) Successful in 1m42s
Build & Push Container Image / publish (push) Successful in 13s
Build Windows Installer / build-windows-installer (push) Successful in 13s
Publish Forgejo Release / publish-release (push) Successful in 10s
|
||
|---|---|---|
| .agents/skills/impeccable | ||
| .cursor | ||
| .github | ||
| android | ||
| custom_components/marinara_engine | ||
| docs | ||
| e2e | ||
| packages | ||
| scripts | ||
| win | ||
| .dockerignore | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| .markdownlint.json | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| DESIGN.json | ||
| DESIGN.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| Dockerfile.lite | ||
| hacs.json | ||
| LICENSE | ||
| MARI_SUGGESTION_CHIPS_TASK.md | ||
| MarinaraLauncher.exe | ||
| package.json | ||
| playwright.config.ts | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| PRODUCT.md | ||
| README.md | ||
| skills-lock.json | ||
| start-local.bat | ||
| start-termux.sh | ||
| start.bat | ||
| start.sh | ||
| tsconfig.base.json | ||
| tsconfig.json | ||
🍜 Guksu Motor
Fun. Intuitive. Plug-And-Play.
A local, AI-powered chat, roleplay, and game engine built around one idea: you install it, you run it, and it just works. Oh, and don't forget about the part where you have fun! ALSO, HEY, LOOK, IT'S FREE.
Created with agentic use in mind, allowing multiple requests at once. Everything is connected. Chat with your characters OOC about your roleplays. Have them create RP scenes for you. All designed with simplicity in mind: we don't want to spend hours on setup, we just want to play.
⚠️ Alpha Software — Early release. Expect rough edges, missing features, and breaking changes. Bug reports and feedback are very welcome!
About the Guksu Fork
Guksu Motor is a Spicy Fork of Marinara Engine. It keeps Marinara's local-first chat, roleplay, and game foundations, while concentrating on memory systems and unapologetically experimental ideas.
This fork works with a move-fast-and-break-things mentality. Expect experiments to arrive early, change shape, occasionally bite, and get better in public. Keep backups, report the weird stuff, and do not mistake alpha software for a promise carved into stone tablets.
Guksu Fork Additions
- Honcho Memory support — An optional global Memory Recall backend for durable, semantic memory across chats. It can use hosted Honcho or a self-hosted Honcho-compatible service; ordinary local Memory Recall remains available when Honcho is off or unavailable.
- Memory controls that are actually controllable — Tune search query depth independently from retrieved context: set how much recent conversation forms the Honcho search query, how many session messages can return, and how many peer observations can return. Setting either retrieval limit to
0disables that category. - Memory lifecycle controls — Saved characters and personas can purge their own Honcho conclusions and Guksu-owned session membership from their Advanced settings. The app spells out the deletion boundary before it does anything destructive, because memory amnesia should not be a surprise boss fight.
Honcho Memory is experimental and currently tested primarily for roleplaying. Configure it in Settings → Advanced → Honcho Memory. For setup details, self-hosting notes, fallback behavior, and purge boundaries, see Memory Recall.
Table of Contents
Screenshots
Roleplay Mode — Character sprites, custom backgrounds, weather effects, and AI agents
Home screen · Guided onboarding
Conversation Mode — Discord-style DMs with selfies and image generation
Card Browser — Search and import character cards from Chub.ai, JannyAI, CharacterTavern, Pygmalion, Wyvern, and more
Game Mode — AI Game Master, party of characters, generated backgrounds, weather, and time of day
NPC dialogue tracking · Party member card with stats, levels, and abilities
Fully responsive — Conversations, Roleplay, and Game Mode all work on phones and tablets via PWA
Latest Release
Current stable release: v2.3.5.
See CHANGELOG.md for detailed release notes. Tagged releases use the vX.Y.Z format; CI-only revisions may append one lowercase letter, such as vX.Y.Za, while keeping the same package version and release notes. Releases are published on the Releases page with a Windows installer, Android bootstrap APK, and named versioned source ZIP. Android APKs are Termux bootstrap + WebView shells: they can download Termux from F-Droid, launch Android's installer, start the Termux setup flow after required permission prompts, then open the local Guksu server on the same device.
Roadmap
- Free-to-download mobile apps for Android and iPhone
- An engine feature for building and sharing full games with custom sprites, soundtracks, and scenarios
- New game modes: tabletop-style, point-and-click, and classic text adventures
- Ongoing improvements and bug fixes
More detailed public roadmap.
Installation
| Platform | Guide |
|---|---|
| 🐳 Docker / Podman | Container Installation Guide — recommended |
| 🪟 Windows | Windows Installation Guide |
| 🍎🐧 macOS / Linux | macOS / Linux Installation Guide |
| 🤖 Android APK Bootstrap | Android APK Guide — guided tap-through install/start shell |
| 🤖 Android Manual Termux | Android (Termux) Installation Guide — manual fallback |
| 📱 iOS / iPadOS | iOS / iPadOS PWA Guide |
Recommended Android path: download the Android APK from the latest GitHub Release, open it, then tap Install / Start Guksu. The APK can download Termux from F-Droid, hand it to Android's installer, request Termux command permission, start the setup command, and open the local Guksu server when it is ready. If Android blocks that handoff, the APK copies a fresh-Termux setup command that can be pasted into Termux manually. Android still shows its required install/permission prompts.
Each guide covers installation, updating, and LAN access for that platform. See Configuration Reference for environment variables setup. Having trouble? See FAQ and Troubleshooting.
Upgrading from an older release? See Upgrading Guksu Motor for the platform-by-platform upgrade path.
Security defaults are intentionally local-first: loopback access works out of the box, ordinary LAN and public clients require Basic Auth unless you explicitly opt back in, and Tailscale (100.64.0.0/10) plus same-host Docker bridge/gateway traffic are trusted by default for easier private installs. Set BYPASS_AUTH_TAILSCALE=false or BYPASS_AUTH_DOCKER=false if you want those clients to authenticate too. ALLOW_UNAUTHENTICATED_PRIVATE_NETWORK=true restores unauthenticated access for other trusted private networks; public clients still require ALLOW_UNAUTHENTICATED_REMOTE=true. Powerful actions such as backups, bulk import, update apply, sidecar install/download/delete, haptics, and custom tool mutation also require ADMIN_SECRET; see Access Control.
Features
Chat & Roleplay
Three chat modes — Conversation (Discord-style DMs), Roleplay (immersive RPG with sprites and backgrounds), and Game (AI Game Master with party, quests, and combat). Characters can share memory across modes. Create or import characters, search the multi-site Card Browser (Chub.ai, JannyAI, CharacterTavern, Pygmalion, Wyvern, and more), organize chats into folders, branch conversations, swipe between alternate responses, and import from SillyTavern.
Visual & Immersive
Character expression sprites with automatic emotion switching, custom scene backgrounds, dynamic weather overlays, gallery illustrations, short scene videos from generated illustrations, Game Mode storyboards with selectable keyframe and video prompt styles, two visual themes (Y2K Guksu and SillyTavern classic), and light/dark mode.
AI Agent System
An optional one-click catalog of 29 first-party agents and feature packages. Fresh installs stay lightweight with no bundled agents. Open Agents → Download Agents to install only what you want or uninstall packages you no longer need. Installed official packages automatically update to the newest compatible catalog version when the Guksu server starts, while remaining available at their current version when the server is offline. Existing installations retain their agents during Engine upgrades. Package sources, artifacts, and the complete catalog are published in Pasta-Devs/Marinara-Agents. You can also create or import custom agents.
- Writer Agents: Prose Guardian, Continuity Checker, Narrative Director, Knowledge Retrieval, Knowledge Router, and Card Evolution Auditor.
- Tracker Agents: World State, Expression Engine, Quest Tracker, Background, Character Tracker, Persona Stats, Custom Tracker, and Hierarchical Maps.
- Misc Agents: Echo Chamber, Illustrator, Lorebook Keeper, Combat, Immersive HTML, Music DJ, Haptic Feedback, CYOA Choices, Calls, UNO, Chess, Poker, 8-Ball Pool, Tic-Tac-Toe, and Rock-Paper-Scissors.
See the Downloadable Agents Reference for modes, behavior, and setup guidance for every package, or browse the official Agent repository directly.
Prompt Engineering
Preset system with drag-and-drop prompt ordering, lorebooks with keyword triggers, an AI lorebook maker, world info inspector, regex scripts, and a macro/template system.
Connections & Providers
OpenAI, OpenAI ChatGPT subscription login, Anthropic, Claude Subscription through the local Claude Agent SDK, Google Gemini, Google Vertex AI, OpenRouter, NanoGPT, Mistral, Cohere, xAI / Grok, the bundled downloadable Local Model sidecar, Pollinations, Stability AI, Together AI, NovelAI, Venice.ai, ComfyUI image and local video workflows, SD Web UI, Draw Things (Apple Silicon, Metal + Apple Neural Engine), Google AI Studio video models (Gemini Omni and Veo), xAI Imagine video, OpenRouter video, Seedance 2.0 video, and custom OpenAI-compatible endpoints. API keys are encrypted at rest with AES-256. Per-chat connection overrides.
Export & Data
Export individual chats or bulk transcript zips as JSONL or plain text. Fully local file-native storage — all data stays on your machine. No account required.
Documentation
The full guide library is browsable inside the app: open Documentation from the Home screen to search every guide, organized by category. Highlights:
| Document | Description |
|---|---|
| docs/INSTALLATION.md | Installation guide index (all platforms) |
| docs/CONFIGURATION.md | Environment variables and .env reference |
| docs/conversation/getting-started.md | Conversation Mode setup, DMs, groups, profiles (display name, about me, behavior), calls, selfies, and table games |
| docs/roleplay/getting-started.md | Roleplay Mode setup, sprites, HUD, agents, and connected chats |
| docs/game/getting-started.md | Game Mode setup, world-gen, party play, storyboards, and troubleshooting |
| docs/agents/built-in-agents.md | Complete reference for all 29 downloadable first-party agents and feature packages |
| docs/noodle/overview.md | Noodle social timeline: setup, posting, interactions, images, and chat carryover |
| docs/prompts/generation-parameters.md | Sampler and output-parameter reference across providers |
| docs/REMOTE_ACCESS.md | Remote access, Basic Auth, IP allowlists, and admin access |
| docs/conversation/calls.md | Conversation audio-call setup, Local Whisper, TTS, and troubleshooting |
| docs/media/image-providers.md | Image generation provider setup |
| docs/media/comfyui.md | Local and RunPod ComfyUI workflow export, placeholders, reference images, and troubleshooting |
| docs/media/style-profiles.md | Image style profiles and prompt grammar |
| docs/media/tts-setup.md | Text to speech (TTS) setup and voices |
| docs/media/scene-video.md | Scene-video provider setup and the Gallery animation workflow |
| docs/game/storyboard.md | Step-by-step guide to manual and automatic Game Mode storyboards |
| docs/agents/agents-overview.md | Agent system overview: phases, per-chat enablement, built-in and custom agents |
| docs/extending/custom-tools.md | Function calling, custom tools, webhooks, scripts, and agent tool enablement |
| docs/prompts/presets.md | Preset editor, prompt sections, groups, ordering, and variables |
| docs/extending/regex-scripts.md | Regex scripts, prompt/display scope, depth, order, and safety |
| docs/agents/knowledge-sources.md | Knowledge Sources, RAG, Retrieval vs Router, and embedder notes |
| docs/characters/bot-browser.md | Multi-site Card Browser search and character import guide |
| docs/conversation/emoji-stickers-gifs.md | Custom emoji/sticker uploads and selection modes |
| docs/TROUBLESHOOTING.md | Common issues and fixes |
| docs/FAQ.md | Frequently asked questions (LAN access, etc.) |
| docs/prompts/macros.md | Prompt macro syntax, including weighted random choices |
| docs/home/professor-mari.md | Built-in assistant capabilities, limits, and safety notes |
| docs/development/frontend.md | Frontend architecture, components, hooks, and API reference |
| docs/development/architecture-map.md | Code ownership map and module-boundary refactor groundwork |
| android/README.md | Android Termux bootstrap + WebView shell guide |
| CONTRIBUTING.md | Contributor workflow, validation, versioning, and release steps |
| CHANGELOG.md | Release notes |
| CLAUDE.md | Maintainer notes for contributors using Claude |
Community & Support
- Join our Discord — Chat, get help, share characters, and give feedback
- Support on Ko-fi — Help keep the project alive
Contributors
Made with contrib.rocks.