Appearance
Why Hapimatic?
Hapimatic is based on hapi, which was built as a self-hosted alternative to Happy, an excellent project. This page explains the local-first design Hapimatic inherits from hapi, and how it differs from Happy's cloud-first design.
The short answer: Happy is designed for cloud hosting with multiple users. The design Hapimatic inherits is for self-hosting with a single user or small team. These different goals lead to fundamentally different architectures.
Self-hosted and Hapimatic Cloud
The data claims on this page describe the self-hosted core: Hapimatic's server, database, and web app run on a machine you control, and no Hapimatic relay service sits in between. If you reach it from outside your network through a tunnel (Cloudflare Tunnel, ngrok) or turn on Telegram notifications, that provider carries the traffic. Cloudflare Tunnel and ngrok's HTTPS endpoints end TLS at the provider's edge, so the provider can read that traffic, including the access token you sign in with; Tailscale (including Funnel) ends TLS on your own machine. Your agents still send prompts and code to their model providers, as they do without Hapimatic. On Hapimatic Cloud, your sessions run on a VM that the operator can access; see Consent & Data Handling.
TL;DR
| Aspect | Happy | Hapimatic |
|---|---|---|
| Design | Cloud-first | Local-first |
| Users | Multi-user | Single user / small teams |
| Session data | Encrypted on server | Stored on a server you run |
| Deployment | Multiple services | Single binary |
| Complexity | High (E2EE, scaling) | Low (one program, no E2EE layer) |
The local-first design fits if: You want personal or small team use, data sovereignty, and minimal setup.
Choose Happy if: You need large-scale multi-user collaboration or enterprise features.
Architecture Comparison
Happy: Cloud-First
Happy's cloud design requires:
- End-to-end encryption - Because you don't trust the server
- Distributed database + cache - Because you need to scale
- Complex deployment - Docker, multiple services, config files
┌─────────────────────────────────────────────────────────────────────────┐
│ PUBLIC INTERNET │
│ │
│ ┌─────────────┐ ┌─────────────────────────────────┐│
│ │ │ │ ││
│ │ Mobile App │◄───── E2EE ───────►│ Cloud Server ││
│ │ │ │ ││
│ └─────────────┘ │ ┌─────────────────────────────┐││
│ │ │ Encrypted Database │││
│ │ │ (server cannot read) │││
│ │ └─────────────────────────────┘││
│ └────────────────┬────────────────┘│
│ │ E2EE │
└───────────────────────────────────────────────────────┼─────────────────┘
▼
┌───────────────────┐
│ CLI │
│ (holds the keys) │
└───────────────────┘Hapimatic: Local-First
Hapimatic's local design simplifies everything:
- No E2EE needed - Session data is stored on a server you run, not on a relay service
- Single embedded database - No scaling required
- Single-binary deployment - The server, web app, and CLI ship as one program; see Installation
┌────────────────────────────────────────────────────────────────────────┐
│ PRIVATE NETWORK │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Single Process / Binary │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ CLI │◄──►│ Server │◄──►│ Web App │ │ │
│ │ └──────────┘ └────┬─────┘ └──────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌────────────────┐ │ │
│ │ │ Local Database │ │ │
│ │ │ (plaintext) │ │ │
│ │ └────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ localhost │
└────────────────────────────┼───────────────────────────────────────────┘
│
┌────────▼────────┐
│ Tunnel (Optional)│
│ for remote access│
└─────────────────┘Key Differences
Data Location
| Aspect | Happy | Hapimatic |
|---|---|---|
| Where data lives | Cloud server | A server you run (your machine or a VPS) |
| Who can access | Server stores encrypted blobs | You, anyone holding your access token (or a Telegram account bound with it), anyone with access to the server's machine (including your VPS host, if you use one), and a tunnel provider that ends TLS at its edge (Cloudflare Tunnel, ngrok) |
| Trust model | Don't trust server → E2EE | Trust your own server → TLS that ends on it |
Deployment Model
Happy requires orchestrating multiple components:
┌───────────────────────────────────────────────────────────────────┐
│ Distributed Services (4+ components) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Database │ │ Cache │ │ Storage │ │ Server │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Requires: Container orchestration, multiple config files │
└───────────────────────────────────────────────────────────────────┘Hapimatic bundles everything:
┌───────────────────────────────────────────────────────────────────┐
│ Single Binary (everything bundled) │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CLI + Server + Web App + Database (embedded) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Requires: hapi, git, python3, and jq │
└───────────────────────────────────────────────────────────────────┘Security Approach
| Aspect | Happy | Hapimatic |
|---|---|---|
| Problem | Data on untrusted server | External access to local data |
| Solution | End-to-end encryption | Tunnel with TLS |
| Complexity | High (key management) | Low (tunnel setup) |
| Data at rest | Encrypted | Plaintext (protected by OS) |
Why Different Architectures?
Happy's Constraints
Goal: Multi-user cloud platform
│
├──► Users don't trust your server
│ └──► Must encrypt everything (E2EE)
│
├──► Many concurrent users
│ └──► Must scale horizontally
│
└──► Multiple devices per user
└──► Must sync state across devicesResult: Sophisticated but complex architecture
The Local-First Simplifications
Goal: Self-hosted tool for individuals or small teams
│
├──► Session data stays on a server you run
│ └──► No E2EE needed
│
├──► Limited users (via namespaces)
│ └──► No horizontal scaling needed
│
└──► Your own server holds the shared state
└──► No third-party sync serviceResult: Simple and portable architecture
Summary
| Dimension | Happy | Hapimatic |
|---|---|---|
| Philosophy | Cloud-first | Local-first |
| Data location | Server (encrypted) | Your own server (plaintext) |
| Deployment | Multiple services | Single binary |
| Scaling | Horizontal | None needed |
| Encryption | Application-layer E2EE | Transport-layer TLS |
| Target user | Teams, cloud users | Individuals, small teams, self-hosters |
Conclusion
The architectural differences stem from fundamentally different goals:
Happy: Built for multi-user cloud scenarios. Solves the "untrusted server" problem with E2EE, at the cost of deployment complexity
The local-first design Hapimatic inherits: Built for individuals or small teams who self-host. Solves the "remote access" problem with simple networking, which is what lets it ship as a single program
If you self-host for personal or small team use, this design avoids the complexity Happy's cloud service needs. If you would rather have a VM hosted for you, Hapimatic Cloud is in pilot; see Hapimatic Cloud.