Maat Documentation

Maat is a free, open-source mobile application that lets you chat securely with your locally hosted Large Language Models — via LM Studio — from anywhere on your home network.

By utilizing a native desktop application (PyQt6 + FastAPI) on your PC and a fast Flutter mobile client, Maat ensures that all inference runs on your own hardware. Your chats remain 100% private, with zero data sent to the cloud. Setup takes less than a minute via a simple QR code scan.

Features

Architecture

Maat is split into two main components that communicate over your local Wi-Fi network:

Prerequisites

Before setting up Maat, ensure you have the following installed on your system:

Quick Start

Get Maat running in under a minute with these two steps.

cd gateway
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python main.py

cd mobile
flutter pub get
flutter run

cd gateway
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

cd mobile
flutter pub get
flutter run

cd gateway
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

cd mobile
flutter pub get
flutter run

A native desktop window will open displaying your pairing QR code. Open the Maat app and scan it to pair. That's it!

Pairing Guide

Maat uses a QR-code based pairing system to securely connect your mobile device to the gateway without manual IP configuration.

Troubleshooting

Gateway API Overview

The Maat Gateway exposes a RESTful API built with FastAPI. All endpoints (except /health and /pair) require a valid X-Device-Token header obtained through the pairing process.

The default base URL is http://<your-pc-ip>:8080.

Health Check

{
  "status": "ok",
  "lmstudio": true,
  "version": "0.1.0",
  "gateway": true
}

Pairing

{
  "server": "http://192.168.1.100:8080",
  "device_name": "MY-PC",
  "pairing_token": "a1b2c3d4..."
}

{
  "device_name": "My Phone",
  "pairing_token": "a1b2c3d4..."
}

{
  "success": true,
  "device_id": "uuid-device-token..."
}

Models

[
  { "id": "qwen2.5-coder-7b-instruct" },
  { "id": "llama-3.1-8b-instruct" },
  { "id": "gemma-2-9b-it" }
]

{
  "success": true,
  "model": "qwen2.5-coder-7b-instruct"
}

Chat

{
  "conversation_id": "optional-uuid",
  "model": "qwen2.5-coder-7b-instruct",
  "message": "Explain quicksort in Python",
  "personality": "coding_partner"
}

{
  "conversation_id": "your-conversation-uuid"
}

{
  "conversation_id": "your-conversation-uuid"
}

Conversations

{
  "title": "My Python Chat"
}

Gateway Configuration

The gateway can be configured via environment variables (in a .env file in the gateway/ directory) or CLI arguments.

CLI Arguments

python main.py --port 9090 --host 0.0.0.0 --lmstudio-url http://localhost:1234

Mobile App

The mobile client is a Flutter application built with Material 3 and Riverpod for state management.

Project Structure

mobile/
├── lib/
│   ├── screens/
│   │   ├── chat/           # Main chat interface
│   │   ├── personality/    # AI persona selection
│   │   ├── qr_connection/  # QR code scanner & pairing
│   │   ├── settings/       # App settings
│   │   └── splash/         # Splash screen
│   ├── theme/              # App-wide theming (Material 3)
│   └── widgets/            # Reusable UI components
├── assets/
│   └── logo.png
└── pubspec.yaml

Key Dependencies

Building from Source

# Debug build (runs on connected device/emulator)
cd mobile
flutter pub get
flutter run

# Release APK build
flutter build apk --release

How to Contribute

We are building Maat in public and are actively looking for contributors! Whether you are a student looking for resume experience, a Flutter developer, or a Python backend engineer, we want your help.

Roadmap

Maat is currently at Version 0.1 MVP. Here's what's planned for future releases: