retoorandClaude Sonnet 5.5 6d80dd0223 feat(clients): audio: ElevenLabs, AssemblyAI, Deepgram, Cartesia, Speechmatics, Hume
Table driven REST (509 rows verified against vendor specs by tools/check_spec.py),
WebSockets over the src/google/live client, neutral SpeechSynthesizer /
SpeechRecognizer seam, /ai/audio demo with dry runs, 110 package tests and 5
route tests. PlayHT has no public API; LeMUR is gone from AssemblyAI's spec.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 15:36:57 +01:00
2026-10-24 08:40:50 +02:00
2026-10-24 08:40:50 +02:00

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 BSD make
  • libwolfssl (TLS; the example and the Google/vendor libs link -lwolfssl)
  • libsqlite3 and libpq (the CLI links -lsqlite3 -l:libpq.so.5)
  • Optional: Postgres 18 for the postgres backend (docker compose up -d postgres)
  • Optional: python3 for make verify, pip install locust for 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: builds build/google/sa-token, mints a service-account access token into GOOGLE_ACCESS_TOKEN, then runs the whole Google suite (hermetic tests plus live tests) with MOLO_LIVE_NET=1. Needs GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_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 loud API NOT ENABLED instead of failing quietly.
  • MOLO_LIVE_NET=1 make ai-test: same for the vendor packages, using XAI_API_KEY, ANTHROPIC_API_KEY, META_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY and the admin / management keys. Missing keys give a loud SKIP. Calls that cost real money also need MOLO_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, model molodetz; override with --base-url and --model.
  • Today it prints the model's answer. It does not write files yet, so the plan-then-apply flow in src/cli/spec.md is 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 serve without --reload only waits for a signal; it does not serve HTTP (src/cli/dev/dev_server.cpp, run_once). With --reload it rebuilds and restarts ./build/molo-app on change.
  • molo ai prints answers only: no file writes, no durable sessions (src/cli/cli/cli_app.cpp, cmd_ai).
  • molo expose serve|agent do not carry traffic; the shorthand molo expose <upstream> key@server /claim from reverse.md is not wired (src/cli/cli/expose_cli.cpp).
  • molo supervisor, task and migrate exit 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 still tls-stub-no-wolfssl, example/fw/Tls.cpp); the swap to src/ 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.
S
Description
moloapp
Readme
5.2 MiB
Languages
C++ 90%
Python 3.2%
Pawn 3.2%
POV-Ray SDL 1.3%
JavaScript 1.1%
Other 1.1%