MoloApp
Native C++23 web framework: HTTP/1.1 + HTTP/2 runtime, routing, views,
validation, templates, ORM (SQLite + Postgres), sessions, realtime,
supervisor, clients, observability, multi-tenancy, audit, governance, plus
clients for Google Cloud and the main LLM vendors. One third-party dependency
for TLS (wolfSSL). One CLI binary: molo. Current version: see VERSION
(0.1.0), history in CHANGELOG.md.
This README states what works today. Gaps are listed at the bottom and in
the spec next to the code that will close them. Where README and a spec
disagree, the spec wins: plan.md, plans/, src/*/SPEC.md, reverse.md,
example/SPEC.md.
Requirements
- Linux,
g++15+ with-std=c++23, GNU or BSDmake libwolfssl(TLS; the example and the Google/vendor libs link-lwolfssl)libsqlite3andlibpq(the CLI links-lsqlite3 -l:libpq.so.5)- Optional: Postgres 18 for the postgres backend (
docker compose up -d postgres) - Optional:
python3formake verify,pip install locustfor load tests
g++ --version && make --version
Build and test
make # everything: libs, tests, build/molo, living server
make test # whole suite, every part
make lint # warning-free build plus em dash ban
make cve-audit # vulnerability-class regression checks, see audit/README.md
make deploy # restart the living server from build/ on :8080, pid file, health wait
make verify # live check of the deployed server (health, metrics, 360px markup, top 10 routes)
make clean # rm -rf build
Everything lands under build/. Warnings are errors in spirit: fix the
cause, never silence them. Per-part targets (google, google-test, ai,
ai-test, data-test, cli-test, ...) also run standalone.
The living example
A route-level demo of every feature, with 205 integration tests on the real stack (no mocks). Standalone, no other part needed.
make -f example/example.mk example # build
./build/example/living-server 8080 # run
make -f example/example.mk example-test # expect: 205 passed, 0 failed
Open http://127.0.0.1:8080/ and click through the matrix. Narrow the
window to 360px: the nav collapses into a dropdown. Quick probe:
curl localhost:8080/health # {"status":"ok", ...}
Load test every route with Locust (pip install locust, see
example/README.md):
make -f example/example.mk example-locust # coverage gate first, then headless run
Open /stats for live Chart.js charts of requests, latency, bytes and
connections (Chart.js is embedded into the binary at build time). The
feature -> route -> test -> plan matrix lives in example/README.md.
Open /voice for a live spoken conversation (needs a Google API key with
Text-to-Speech, Speech-to-Text and Generative Language enabled):
GOOGLE_API_KEY=... ./build/example/living-server 8080 # then open /voice
Click Start, talk, pause: the answer is spoken back, and speaking over it
interrupts it. Optional env: GOOGLE_VOICE_LANG (default nl-NL),
GOOGLE_VOICE_NAME, GOOGLE_GENAI_MODEL (default gemini-3.5-flash), GOOGLE_STT_MODEL, GOOGLE_TTS_MODEL (default gemini-2.5-flash-tts), GOOGLE_API_BACKEND.
The Google layer is src/google (spec: src/google/SPEC.md, plan
plans/16-agent-platform.md). No test scripts a Google reply: each module
is derived from Google's Discovery documents and re-checked by
src/google/<module>/tools/check_discovery.py; make google-live
runs read-only live checks against real Google (a service-account token is
minted for the OAuth-only APIs).
Live checks
Which Google APIs to enable (with console links) is in src/google/APIS.md;
where to create each vendor key is in src/llm/SPEC.md section 5.
Hermetic tests never touch the network and ignore .env.json.local
(MOLO_ENV_FILES=off). Live checks are opt-in:
make google-live: buildsbuild/google/sa-token, mints a service-account access token intoGOOGLE_ACCESS_TOKEN, then runs the whole Google suite (hermetic tests plus live tests) withMOLO_LIVE_NET=1. NeedsGOOGLE_APPLICATION_CREDENTIALSandGOOGLE_CLOUD_PROJECT. Live tests are read-only or a few tokens; none creates, updates or deletes a resource. An API that is disabled on the project prints a loudAPI NOT ENABLEDinstead of failing quietly.MOLO_LIVE_NET=1 make ai-test: same for the vendor packages, usingXAI_API_KEY,ANTHROPIC_API_KEY,META_API_KEY,DEEPSEEK_API_KEY,OPENAI_API_KEY,OPENROUTER_API_KEYand the admin / management keys. Missing keys give a loud SKIP. Calls that cost real money also needMOLO_LIVE_PAID=1.
Credentials (environment, then .env.json.local, then .env.json):
GOOGLE_API_KEY (Vertex express keys, voice), GOOGLE_CLOUD_PROJECT,
GOOGLE_CLOUD_LOCATION, and for OAuth-only APIs either
GOOGLE_ACCESS_TOKEN or a service account key file in
GOOGLE_APPLICATION_CREDENTIALS (git-ignored .secrets/). make google-token && ./build/google/sa-token prints an access token.
The Agent Platform demo pages are under /agent/<module> and, like all
/voice, /google, /agent and /ai routes, are excluded from locust.
Other vendors (plan plans/17-llm-vendor-platforms.md, shared layer
src/llm/SPEC.md): pages /ai/xai, /ai/xai/platform, /ai/anthropic,
/ai/anthropic/admin, /ai/meta, /ai/deepseek, /ai/openai,
/ai/openai/platform, /ai/openai/admin, /ai/openrouter. Keys go in
.env.json.local or the environment: XAI_API_KEY, XAI_MANAGEMENT_KEY,
ANTHROPIC_API_KEY, ANTHROPIC_ADMIN_KEY, META_API_KEY (or
MODEL_API_KEY), DEEPSEEK_API_KEY, OPENAI_API_KEY, OPENAI_ADMIN_KEY,
OPENROUTER_API_KEY, OPENROUTER_MANAGEMENT_KEY. Without a key a page and
its status route still load and every calling route answers 503
not_configured; paid or destructive routes are dry runs unless the body has
"confirm":true. MOLO_LIVE_NET=1 make ai-test adds opt-in live checks;
anything that costs money also needs MOLO_LIVE_PAID=1. No vendor key
exists in this repo's environment yet, so every vendor package is verified
against its published spec and unauthenticated probes only.
Test conventions (one test file per URL, Arrange/Act/Assert, integration
only) are in tests/README.md.
How an app is written
example/app/App.cpp is the reference: an Application, middleware slots,
and Routers mounted with a prefix. Apps chain, so mounting three apps
under each other serves /app1/app1/app1/....
auto app = std::make_shared<fw::Application>();
app->use(fw::MiddlewareSlot::Errors, fw::errors_middleware());
fw::Router routing;
register_routing_demo(routing, services);
app->include_router("/routing", routing, "routing.");
Note: example/fw/ is a skeleton of the public API that the real parts
under src/ are being re-bound to, route by route. URLs and tests stay
stable while that happens.
The CLI: molo
Built by make to build/molo.
./build/molo --help
./build/molo help <command> # full help for one command
Global flags: --format json|text, -v (repeat up to 3), -q, -h.
Exit codes: 0 ok, 1 runtime, 2 usage, 69 unavailable. Stdout is the
primary output only; logs go to stderr. --format json is always parseable.
| Command | What it does |
|---|---|
new <name> [--backend postgres|sqlite] [--force] |
Scaffold a project (Makefile, AGENTS.md, .env.json, assets, templates, locales, git init). Refuses a non-empty dir without --force. |
serve [--port N] [--reload] [--config F] |
Dev server. --reload watches and rebuilds; refused on prod config without --allow-prod. |
build [--embed dir] [--out dir] |
Build, optionally embedding assets first. |
embed <dir> --out f.cpp [--hpp f.hpp] [--namespace ns] [--gzip] |
Turn a static dir into constexpr C++ arrays. Output is byte-identical across runs. |
migrate [--check | --apply] |
Preview or apply database migrations. |
health |
Local liveness and readiness summary. |
supervisor start|stop|restart|status|logs |
Process supervisor. Exits 69 until the supervisor is wired in. |
task enqueue|retry|cancel|inspect |
Background task queue (--id for inspect). Same wiring caveat. |
ai new|continue |
The AI agent, see below. |
expose serve|agent|list|stats|expose-key rotate |
Reverse tunnels, see below. |
verify [dir], supply-check [dir], release --commit SHA --suite-stamp F |
Offline artifact verification, pin and advisory gate, ordered release gate. |
rollout start|abort, rollback, experiment start|abort, debug snapshot |
Operability: rolling or blue-green rollout (--strategy --instances --batch --max-unavailable), chaos experiment (--blast --duration --max-burn), debug snapshot. These are one-shot: abort and rollback report that nothing runs in the process. |
Fixed health paths on a running server, no auth: /healthz, /readyz,
/startupz, /metrics (Prometheus text 0.0.4).
Start a new app:
./build/molo new shop --backend sqlite
cd shop && ls -A # .env.json AGENTS.md Makefile assets locales src templates
The agent: molo ai
OpenAI-compatible vibe-coding harness with a framework-aware system prompt.
Streams by default. The prompt comes from --prompt, the first argument, or
piped stdin.
export DEVPLACE_API_KEY=... # env only, never a flag or a file
./build/molo ai new --prompt "a todo app with sqlite and a json api"
echo "add login" | ./build/molo ai continue
./build/molo ai new --prompt "..." --format json # {"ok":true,"text":"..."}
- Defaults: base
https://devplace.net/openai/v1, modelmolodetz; override with--base-urland--model. - Today it prints the model's answer. It does not write files yet, so the
plan-then-apply flow in
src/cli/spec.mdis not implemented. continue [name]resumes by name within one process only; there is no durable session store.- Caps: 30 s connect, 300 s session, 8 MB transcript, 50 actions.
Calling vendors from your own code is a separate layer: src/llm plus
src/openai, src/anthropic, src/xai, src/meta, src/deepseek,
src/openrouter and src/google, demoed under /ai/*, /agent/*,
/google and /voice in the living example (see above).
Reverse tunnels: molo expose
Publish a local endpoint through a MoloApp server over one outbound
connection. The spec is reverse.md (claims, keys, upstream tables,
routing precedence, caps). The protocol pieces (claims, upstream table,
tunnel, proxy) live in src/realtime/expose/. The CLI is a thin front end
and does not run a live tunnel yet:
molo expose serve --slug /hook1 --upstream http://127.0.0.1:3000 # validates, registers the claim in-process, starts stats
molo expose agent --slug /hook1 --key <key> [--server URL] # validates args, prints the target, exits
molo expose list # tunnels registered in this process
molo expose stats [--format json] # reads the stats store
molo expose expose-key rotate --slug /hook1
Stats are zero-cost on the hot path (atomics), flushed in one transaction to
SQLite by default (system.db) or Postgres. Per method: count, kB up/down,
windowed kB/s, average latency.
Configuration
Order, highest first: environment, .env.json.local (git-ignored, put
secrets here), .env.json. .secrets/ is git-ignored too.
{
"DATABASE_URL": "sqlite://system.db",
"STATS_FLUSH_SECS": "5"
}
| Key | Default | Meaning |
|---|---|---|
DATABASE_URL |
sqlite://system.db |
sqlite://... or a postgres URL |
STATS_FLUSH_SECS |
5 |
Stats flush interval |
DEVPLACE_API_KEY |
none | Env only. Required by molo ai |
MOLO_EXPOSE_KEY |
none | Claim key for the expose agent (specified in reverse.md; the CLI reads --key) |
GOOGLE_API_KEY, XAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, ... |
none | Vendor keys for the demo pages, full list in the living example section |
Postgres for local tests: docker compose up -d postgres (user/password
molo, db molo_test, bound to 127.0.0.1:5432).
Repo map
src/runtime event loop, HTTP/1.1 + HTTP/2, compression, static
src/observability logging, events, metrics, tracing (zero-cost when off)
src/security auth, hashing, crypto, sessions, guards, uploads
src/data ORM, drivers, KV, cache, pubsub
src/app application, routers, views, forms, validation, templates
src/realtime WebSocket, SSE, Socket.IO, streaming, WebDAV, expose tunnels
src/supervisor process supervisor, tasks, replication
src/clients HTTP/REST client, OpenAPI, test double
src/llm shared layer for the vendor platforms below (client, SSE, errors, ChatModel)
src/xai src/anthropic src/meta src/deepseek src/openai src/openrouter
whole public API platforms of Grok, Claude, Meta Model API (Muse Spark),
DeepSeek, OpenAI and OpenRouter, one dir per work package
src/google Google Cloud: generic client, OAuth + service accounts, voice, and the
Gemini Enterprise Agent Platform (models, runtime, sessions, sandbox,
registry, armor, optimize, adk, live), one dir per module
src/cli molo binary: CLI, dev server, embedder, AI, ops, i18n, CSP
src/tenancy multi-tenancy
src/audit hash-chained audit log, GDPR export/erasure, retention
src/governance API keys, versioning, OpenAPI diff gate, surface linter
src/operability deploys, drains, locks, breakers, SLO, chaos
src/supplychain SBOM, provenance, pin policy, release attestation
audit/ vulnerability-class regression checks (make cve-audit)
tools/ deploy verification, release and token helpers
example/ living example (skeleton fw + demo routes, Locust file)
tests/ integration tests, mirrors URLs
plans/ 17 detailed plans, index in plans/README.md
Each part ships a <part>.mk fragment that the root Makefile includes, and
most ship a SPEC.md. Every knob has a hard static cap, declared in that
part's caps header (CLI: src/cli/caps.hpp).
Working with agents on this repo
AGENTS.md is the entry point for autonomous work. Pipeline order:
lint, suite, bump, changelog, commit, tag, deploy (make deploy), verify
(make verify). Commits are <type>[(scope)][!]: <description> (subject
max 100 chars). Versions are derived from commits, never hand-chosen:
VERSION and CHANGELOG.md are written by the release tool. Never cross
alone: specs/, CHANGELOG.md, VERSION, tags, history rewrite, force push.
Known gaps
Measured on this checkout, not aspirational:
molo servewithout--reloadonly waits for a signal; it does not serve HTTP (src/cli/dev/dev_server.cpp,run_once). With--reloadit rebuilds and restarts./build/molo-appon change.molo aiprints answers only: no file writes, no durable sessions (src/cli/cli/cli_app.cpp,cmd_ai).molo expose serve|agentdo not carry traffic; the shorthandmolo expose <upstream> key@server /claimfromreverse.mdis not wired (src/cli/cli/expose_cli.cpp).molo supervisor,taskandmigrateexit 69 with the null controllers the binary is built with (src/cli/cli/cli_app.cpp).example/fw/is a skeleton, not the real framework (its TLS context is stilltls-stub-no-wolfssl,example/fw/Tls.cpp); the swap tosrc/namespaces is incremental.- Vendor and Google modules are verified against published specs and unauthenticated probes; no vendor key exists in this repo's environment.
- No benchmark numbers are published. Any performance claim without a measurement behind it is not a claim.