Documentation · v0.3.0
Learn IMURUN, guide by guide.
23 guides, synced from the IMURUN repository: installing and running the app, the Liquid Paper interface, the FISH engine, agents and web research, connectors, voice and on-device tuning. About 133 minutes of reading in total.
- Start here · 7 minInstall & run one commandInstall IMURUN with pip or npx, what each package contains, where your data lives, the launch flags, and how to get or build the FISH engine on any platform.
- Start here · 2 minGetting started your first chatLocal-first AI chat with its own inference engine. One process, no cloud: a C++ engine (FISH) runs GGUF models on the CPU, a Python server hosts sessions, tools and connectors, and a vanilla-JS "Liquid Paper" UI opens in a native…
- FISH engine · 7 minFISH engine how it runsFISH is a self-contained CPU inference engine for GGUF models: its own GGUF reader, quantised kernels, tokenizer, sampler, KV cache and hardware planner. It links nothing from llama.cpp or any other runtime. It is compiled to one shared…
01 / 06
Start here
Install IMURUN, load a model and have your first local conversation.
2 guides
- Getting startedLocal-first AI chat with its own inference engine. One process, no cloud: a C++ engine (FISH) runs GGUF models on the CPU, a Python server hosts sessions, tools and connectors, and a vanilla-JS "Liquid Paper" UI opens in a native…
- Install & runInstall IMURUN with pip or npx, what each package contains, where your data lives, the launch flags, and how to get or build the FISH engine on any platform.
02 / 06
The app
The Liquid Paper interface and voice in both directions: what you see and touch.
2 guides
- The Liquid Paper interfaceThe Liquid Paper interface: a no-build HTML, CSS and JavaScript shell served under a strict content security policy, running in a native window or your browser.
- VoiceSpeech in and speech out on your own machine: speech-to-text and text-to-speech that run locally, what works today, how it was measured, and how the interface uses it.
03 / 06
FISH engine
Our own C++ inference engine: how it reads GGUF, plans memory and runs fast on a CPU.
4 guides
- FISH engine architectureFISH is a self-contained CPU inference engine for GGUF models: its own GGUF reader, quantised kernels, tokenizer, sampler, KV cache and hardware planner. It links nothing from llama.cpp or any other runtime. It is compiled to one shared…
- Supported model architecturesWhich GGUF model families and quantisation types FISH can run, what is special about each one, and which are verified with real files versus implemented.
- GPU offload (Vulkan)FISH's Vulkan GPU backend: per-matmul offload, whole-layer spans with a device-resident KV cache, optional re-quantisation for more layers in VRAM, and how to switch each on.
- Engine benchmarksMeasured FISH kernel, prefill and decode speeds on a Ryzen 7 laptop with Llama-3.2-1B Q4_K_M, with the conditions and caveats behind every number.
04 / 06
Agents & research
Tools the model calls itself, skills, sub-agents and web research with numbered sources.
3 guides
- Agents: tools, permissions, skillsHow the assistant calls tools by itself: the turn loop, what each tool may touch, approval cards for anything that writes, and skills and sub-agents.
- Research engineHow IMURUN searches the web with no API key: the model decides whether to search and writes the queries, sources run in parallel, and only cleaned, ranked passages with numbered sources reach it.
- Browser search helperThe opt-in browser search source: the protocol IMURUN uses to run searches through a local helper, and what is implemented so far.
05 / 06
Connectors
Your accounts and any MCP server, with OAuth tokens kept in the OS keychain.
10 guides
- ConnectorsIMURUN can act on eight external accounts — Gmail, GitHub, Slack, Vercel, Render, Cloudflare, Supabase and Canva — through tools named <service>_<verb> in the agentic tool loop (docs/agentic/README.md), and through MCP (MCP.md).
- MCP serversUse the tools of any Model Context Protocol server inside IMURUN: adding a server, how its tools are registered, and the safety rules they follow.
- GitHub connectorConnect GitHub to IMURUN, by browser sign-in or a device code, and use its tools from chat; what it can do and how writes are approved.
- Gmail connectorSearch, read, label, draft and send email from the user's Gmail through the model's tool loop. Code: services/connectors/providers/gmail.py (REST), providers/gmail_mime.py (MIME decode / RFC 2822 build),…
- Slack connectorConnect Slack to IMURUN and use its tools from chat: how sign-in works, what it can do, and how writes are approved.
- Canva connectorConnect Canva to IMURUN and use its tools from chat: how sign-in works and what it can do.
- Cloudflare connectorCloudflare's OAuth is partner-only, so Cloudflare connects with a scoped API token the user creates and pastes into IMURUN. The token is verified before it is saved, kept in the encrypted secret store, and never shown again. Code:…
- Render connectorRender has no third-party OAuth, so it connects with an API key the user creates and pastes into IMURUN. The key is verified before it is saved, kept in the encrypted secret store, and never shown again. Code:…
- Supabase connectorConnect Supabase to IMURUN and use its tools from chat: how sign-in works, what it can do, and how writes are approved.
- Vercel connectorConnect Vercel to IMURUN and use its tools from chat: how sign-in works, what it can do, and how writes are approved.
06 / 06
Tuning & roadmap
Teach IMURUN from your own use, on your own machine, and see what comes next.
2 guides
Read it, then improve it.
Every guide here is markdown in the IMURUN repository. If something is unclear or out of date, open an issue or send a patch: the docs and the app ship from the same place.