Malama
About Showcase Engine & Tuning Ingestion Install Developer Portal ↗ GitHub Repository
Native • C++23 • wxWidgets 3.3

Local AI Intelligence.
Private by default. Native by design.

A high-performance Linux desktop client for Ollama. Direct TCP streaming, zero cloud dependencies, and instant local execution.

Get Started Technical Architecture ↗ Download AppImage
Native Markdown Rendering Engine No Electron Bloat
0 KB Cloud Telemetry
C++23 Native Engine
Malama Desktop Workspace

Architected For Performance

Why waste hundreds of megabytes of system RAM running browser wrappers when your GPU and CPU need that memory for local model inference?

⚡

Microscopic Footprint

Built with native GTK-backed wxWidgets 3.3 and C++23. Replaces Chromium/Node.js runtimes with a lightweight compiled native binary.

🔒

Strict Data Sovereignty

Connects directly to your local Ollama daemon over non-blocking Boost.Asio TCP sockets. No remote proxies, no web wrappers, no tracking.

💾

SQLite3 Persistence

Conversations, session titles, pinned items, and hyperparameter states are safely persisted using localized, transactional SQLite queries.

About Malama Interface

Application Showcase

Explore the clean, functional GTK interface designed strictly for Linux productivity.

Home Workspace
Main Chat Workspace: Native Markdown rendering, live code block syntax highlighting, and dynamic context attachment staging.
Sessions View
Session Management: Coordinate-aware hit testing for pinning, renaming, searching, and restoring previous chat sessions instantly.
UI Settings
Appearance Preferences: Custom color styling, font sizing, and real-time observer repainting.
Engine Settings
Ollama Engine Integration: Dynamic model discovery from local /api/tags endpoints, timeout bounds, and reasoning tag filters.
License View
GNU General Public License v3.0: Pure open-source software built for developer liberty and privacy.

Fine-Grained Engine & Session Tuning

Control exact inference behavior per conversation turn or globally across the engine.

Per-Session Granularity

Hyperparameter Tuning & System Overrides

Tweak model behavior on a thread-by-thread basis without breaking application state:

  • Temperature & Top-P: Adjust output randomness and nucleus sampling parameters in real time.
  • Context Window Allocation (num_ctx): Dynamically scale context capacity up to 32,000+ tokens to handle long multi-turn discussions and large document payloads.
  • Custom System Prompts: Inject distinct system personas per session saved directly inside the local SQLite database.
  • Reasoning Block Filtering: Toggle automatic stripping of DeepSeek/Reasoning model <think> blocks on the fly via a background thread state machine.
Engine Tuning Interface

Multimodal Asset Ingestion Engine

Factory-routed parser subsystem capable of reading documents, spreadsheets, eBooks, and vision assets with zero-copy efficiency.

Asset Category Supported Formats Parsing Engine & Strategy Operational Bounds
Plain Text .txt, .md Direct UTF-8 stream ingestion Bounded by available RAM
PDF Documents .pdf Page text extraction via poppler-cpp 4 MB per-file processing limit
Office Documents .docx, .xlsx Archive decompression (libarchive) & XML traversal (pugixml) Bounded XML expansion checks
OpenDocument .odt, .ods ZIP structure decompression & XML body node isolation Boundary-verified extraction
E-Books .epub XHTML manifest extraction and text traversal Sanitizes layout markup
Images (Vision) .png, .png, .jpeg, .webp Binary validation via libpng/libjpeg & Base64 encoding 4 MB cap; requires vision model

Installation & Setup Guide

Step 1 — System Prerequisite

Ollama Daemon & Target Model Provisioning

Malama operates as a native local workspace client. Ensure the local ollama service daemon is installed, running, and populated with at least one local model prior to launching Malama.

2. Verify / Start Ollama Daemon

Confirm the Ollama background service listener is active

systemctl status ollama || ollama serve

3. Pull Recommended Models

Provision standard text/coding agents or multimodal vision models

# Standard Text & Coding Agent
ollama pull ornith

# Multimodal Vision Model
ollama pull gemma4:e4b
⚠️
Multimodal Vision Requirement Notice:

Image attachments (.png, .jpg, .webp) require an active model explicitly equipped with vision architecture capabilities (e.g., gemma4:e4b or qwen2-vl). Text-only agents (such as ornith) will ignore or reject binary image payloads.

Native installation scripts and package pathways across major Linux distributions.

1

Native Automated Script Deployment (Recommended)

Clone the repository and run the native installer script to auto-detect dependencies, compile optimized binaries, and install launcher menu shortcuts:

git clone https://github.com/Magpiny/malama.git
cd malama
chmod +x install.sh
./install.sh

To completely purge application binaries and desktop launchers, run ./uninstall.sh --purge.

2

Manual Build Dependencies

sudo pacman -S --needed git cmake ninja pkgconf gcc \
  wxwidgets-gtk3 sqlite poppler-cpp libarchive pugixml \
  libpng libjpeg-turbo spdlog boost boost-libs
1

Native Automated Script Deployment

git clone https://github.com/Magpiny/malama.git
cd malama
chmod +x install.sh
./install.sh
2

Manual Build Dependencies

sudo dnf install gcc-c++ cmake ninja-build pkgconfig \
  wxGTK-devel sqlite-devel poppler-cpp-devel libarchive-devel \
  pugixml-devel libpng-devel libjpeg-turbo-devel spdlog-devel boost-devel
1

Native Automated Script Deployment

git clone https://github.com/Magpiny/malama.git
cd malama
chmod +x install.sh
./install.sh
2

Manual Build Dependencies

sudo apt-get update && sudo apt-get install -y \
  build-essential cmake ninja-build pkg-config \
  libwxgtk3.2-dev sqlite3 libsqlite3-dev \
  libpoppler-cpp-dev libarchive-dev libpugixml-dev \
  libpng-dev libjpeg-dev libspdlog-dev libboost-all-dev
1

Download Pre-Compiled AppImage

For all other Linux distributions, download the standalone AppImage built directly from GitHub Releases:

wget https://github.com/Magpiny/malama/releases/download/v0.3.1/Malama-v0.3.0-x86_64.AppImage
chmod +x Malama-v0.3.0-x86_64.AppImage
./Malama-v0.3.0-x86_64.AppImage

Required System Libraries & Operational Roles

Library Name Version Requirement Operational Purpose & System Intent
wxWidgets ≥ 3.3 GTK3/4-backed native user interface rendering toolkit
SQLite3 Stable Release Relational conversation history storage & transactional persistence
Boost.Asio ≥ 1.74 Non-blocking asynchronous TCP socket loop for streaming Ollama tokens
poppler-cpp Stable Release PDF document interrogation and UTF-8 text mining parser
libarchive ≥ 3.6 Decompression engine for compressed format files (DOCX, ODT, EPUB)
pugixml ≥ 1.12 Lightweight XPath XML text node traversal for office documents
libpng / libjpeg Stable Release Binary validation and structural header verification for images
Boost.GIL ≥ 1.74 Graphic processing layout validation for multimodal payloads
glaze ≥ 2.0 / v7.8 High-performance compile-time JSON reflection for request payloads
spdlog ≥ 1.12 High-speed thread-synchronized application logging