Show HN: Moumantai – self-hosted, agent-driven apps you can use on any device

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

2 Commits

2 Commits

.claude

.claude

.github

.github

apps @ 54c9345

apps @ 54c9345

branding

branding

clients

clients

docs

docs

scripts

scripts

server

server

shared

shared

.clang-format

.clang-format

.editorconfig

.editorconfig

.gitattributes

.gitattributes

.gitignore

.gitignore

.gitmodules

.gitmodules

.mise.local.toml.example

.mise.local.toml.example

.mise.toml

.mise.toml

.pre-commit-config.yaml

.pre-commit-config.yaml

.prettierrc

.prettierrc

CLAUDE.md

CLAUDE.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

LICENSE

LICENSE

NOTICE

NOTICE

README.md

README.md

SECURITY.md

SECURITY.md

Taskfile.yml

Taskfile.yml

package-lock.json

package-lock.json

package.json

package.json

pyproject.toml

pyproject.toml

tsconfig.base.json

tsconfig.base.json

uv.lock

uv.lock

Repository files navigation

Moumantai (冇問題 / no problem) is an open-source, self-hosted runtime for personal apps that can be owned, adapted, and used across the devices around you.

Describe an app once: its data, capabilities, and interfaces. The server holds the state and application logic, then projects the appropriate face onto the browser, phone, watch, or embedded display in front of you. Code defines the reliable behavior; an LLM-powered agent adds language, interpretation, and judgment within those boundaries.

The result is an app, not a prompt: durable software that can be reused, inspected, shared, and remixed.

You drive; the agent helps.

Quick start · Architecture · Plugin apps · Agent backends · Clients · Develop

Talk to one agent; your mini apps render natively on every screen.

Key features

Yours, end to end — self-host the runtime and own the app's source, data, behavior, appearance, and deployment.

Schema. Tools. Faces. — a deliberately familiar CRUD core: the schema owns state, tools mutate, and faces read. Direct UI and agent calls meet at the same tool boundary.

Code for the known, an agent for the fuzzy — taps and forms stay deterministic; an LLM-powered agent brings language, flexibility, and judgment when useful.

Bring your own agent and model — the agent supplies orchestration and tool use; the model supplies inference. Choose the combination that fits the task, provider, and budget.

Polyphenic apps, native surfaces — one app wears many faces, specialized for each device and context. Thin clients map the same typed protocol to the toolkit that fits — from browsers and phones to watches and embedded panels — while the server carries the heavy compute.

Apps, not prompts — code and interfaces are reused rather than regenerated on every request, saving tokens and making smaller or less expensive models practical. The result can be inspected, shared, forked, and personalized.

Build, preview, promote — a coding agent can draft or edit an app in isolation, validate it, and preview it on paired devices; nothing goes live until you choose to promote it.

Moumantai is early and evolving; expect rough edges and changing APIs. Trying it, reporting what breaks, and contributing improvements are all welcome.

Quick start

Runs the server + PWA locally — the fastest path to a working app. Native clients are opt-in (see Running on your devices).

1. Set up. Clone with the plugin-apps submodule:

git clone --recurse-submodules https://github.com/xiang-deng/moumantai.git cd moumantai

Already cloned without --recurse-submodules? Run: git submodule update --init

Then install the toolchain — install mise (winget install jdx.mise · brew install mise · curl https://mise.run | sh), activate it in your shell (mise activate pwsh|bash|zsh), open a fresh shell, and run:

mise install && uv sync # Node 22, Python 3.12, JDK 17, task, buf, uv npm install # links the TS workspaces (server, pwa, protocol)

1. Configure the server. An interactive wizard sets up the workspace (Moumantai Home — config, secrets, per-app data) and your LLM credential. Its first prompt asks where the workspace lives (default ~/.moumantai/; see Where your data lives):

task server:init

By default the wizard expects a Claude credential — one of:

Credential Format Where to get it

OAuth token sk-ant-oat… claude setup-token (from the Claude Code CLI); best with a Claude Pro/Max plan

API key sk-ant-api… console.anthropic.com

Prefer another agent harness, model, or provider? See Agent backends.

1. Start the server and the PWA in two terminals:

task server:dev # Terminal A — WebSocket on ws://localhost:3000 task pwa:dev # Terminal B — Vite on http://localhost:5174

1. Pair this browser. Pairing is on by default — the server only accepts allowlisted devices. Open an enrollment window:

task server:cli -- device pair # opens a 5-minute enrollment window

Open http://localhost:5174; the PWA shows a pairing code. Back in the device pair prompt, type approve — the browser connects within seconds. (Local-only? Disable with pairingRequired: false via task server:cli -- config edit, but keep it on for any networked server.)

1. Try it. In chat, type:

add 5 dollars for coffee

The spend-tracker plugin app picks it up via the agent, runs its add_expense tool, and re-renders the Summary face. Swipe up/down to switch faces within an app, left/right to switch apps.

Note

The server is a WebSocket endpoint — opening http://localhost:3000 in a browser shows nothing; the PWA (or a native app) is the consumer. Change the port with task server:init.

1. Make it your own. The bundled spend-tracker shows the idea. From here you can:

Install an existing app — from a local path, a git URL, or a registry id:

task server:cli -- app install task server:cli -- app list

Edit one directly — work in TypeScript using the same schema, tool, face, and validation rules used by the coding agent.

Use the coding agent — describe an app or change in the PWA's dev tab, preview its isolated draft, then promote it when ready.

Both are covered in full under Plugin apps.

Where your data lives

The server keeps all runtime state in one directory — Moumantai Home: config.json, secrets in .env, chat history, and each app's SQLite database. The setup wizard's first prompt picks where it goes:

~/.moumantai/ — the default; best for everyday use.

/.moumantai/ — project-local and gitignored; best for development and keeping multiple checkouts / worktrees isolated.

Not sure which home is active (common with multiple clones)? task server:cli -- workspace path prints it and which rule selected it. The full resolution order and the workspace set/reset commands live in server/CLAUDE.md.

Credentials are stored on the server and never sent to clients or plugin apps. The active agent backend uses them to authenticate with the provider you configure; prompts and relevant app context may be sent to that provider.

Important

No standalone binary. There's no moumantai command to install — admin commands run from the checkout as task server:cli -- (e.g. task server:cli -- device list). task server:init is the single setup wizard (first run and reconfigure); task server:cli -- config show / config edit inspect and hand-edit the saved config.

Architecture

Moumantai is a server-authoritative application runtime. The server owns state, execution, and coordination; plugin apps, agent backends, and clients connect through explicit contracts.

Component Responsibility Architectural boundary

Server runtime Owns application state, capability execution, agent orchestration, device coordination, and presentation resolution The authoritative core: state changes and business execution happen here

Plugin app Defines data, capabilities, and presentation through schemas, tools, and faces Uses the app SDK; independent of clients and agent backends

Agent backend Connects an agent harness and its model to app context, tools, and faces May request actions or steer presentation; never mutates app state directly

Shared protocol Defines transport messages, the UI-component vocabulary, and generated TypeScript, Kotlin, and C types The stable contract between the server and client implementations

Client Renders protocol components with its platform toolkit and reports user intent Owns device interaction and rendering, not app data, business behavior, or model credentials

The design follows a few strict boundaries:

Tools mutate; faces read; parameters steer presentation.

The server is authoritative; clients render and report intent.

Agent backends request actions; the server validates and executes them.

Device specialization happens on the server, outside plugin business logic.

Apps do not depend on a particular client, agent harness, or model.

Implementation detail lives with each boundary: the server, app examples, protocol, and client READMEs.

Plugin apps

An app is a small TypeScript plugin: a Drizzle schema, defineTool tools, and defineFace faces. Example apps ship in the apps/ submodule and serve as working references.

Install or remix an existing app

Install from a local path, git URL, or registry id; installed source remains available to inspect and change:

task server:cli -- app install task server:cli -- app list

Edit directly

Write or modify the TypeScript yourself. Humans and coding agents follow the same rules in CLAUDE.md and the build-moumantai-app / edit-moumantai-app skills. Validate app changes with task apps:typecheck.

Use the coding agent

Enable dev mode (MOUMANTAI_DEV_MODE=1, or devMode: true in .moumantai/config.json) and describe an app or change in the PWA's dev tab. The agent works through an isolated draft: draft → validate → preview → promote or discard. Nothing touches the live app until you choose to promote it.

Dev mode is off by default; restart the server after enabling it.

Agent backends

The server integrates intelligence through an agent backend contract. A backend connects its agent harness and chosen model to app context, tools, and faces; the server keeps ownership of tool execution and state.

Backend Agent harness Models / providers Authentication

claude (default) Claude Agent SDK Anthropic Claude OAuth token or Anthropic API key (see Quick start)

pi Pi Coding Agent More than two dozen providers, including Anthropic, OpenAI, Google, and Bedrock Provider API key or OAuth

Select the backend in .moumantai/config.json. Provider/model selection and authentication details are covered in server/CLAUDE.md.

Clients

Clients are independent implementations of the shared protocol. Each maps the same component vocabulary to the toolkit and interaction model that fits its platform.

Client Role Stack Run

PWA Universal browser and installable client; the quickest way to start React + Vite task pwa:dev (or a production mode)

Wear OS Glanceable interaction on a watch Kotlin + Wear Compose task wear-os:install

Embedded panel Ambient, always-on display on a wall or desk ESP-IDF + LVGL (C) task esp32:build && task esp32:flash

Android phone Native phone client and path to device capabilities Kotlin + Compose M3 task android:install

Per-client setup lives in each client's README: PWA · Android · Wear OS · ESP32.

Running on your devices

The PWA has three deliberately different modes:

Mode Command Use

Local development task pwa:dev Vite on http://localhost:5174; no service worker and not installable

Local production task pwa:serve Production bundle on http://localhost:4173; installable on the host because localhost is a secure context

Secure remote task pwa:serve:tailscale TAILSCALE_HOST=..ts.net Production bundle for a phone or another tailnet device over HTTPS/WSS

For secure remote acc

[truncated for AI cost control]