Quick start

Desired-state reconciliation is the core model: apply / remove update cluster and host specs; nodes reconcile Docker; the gateway watches routes and proxies HTTP/WebSocket traffic to the owning node, including scale-to-zero cold starts.

momo gateway --config cluster.yml
momo node --node-id node-a --store file://./momo-state
momo apply -f app.yml --node node-a
momo remove app-id
momo status
momo doctor

Local one-node

# Terminal 1 — node (file store for single-process dev)
momo node --node-id node-a --store file://./momo-state --auto-register

# Or use SQLite for single-host multi-process:
# momo node --node-id node-a --store sqlite://./momo.db --auto-register

# Terminal 2 — gateway
momo gateway --store file://./momo-state --bind 127.0.0.1:8080

# Apply a sample app (build images first with `make samples`)
momo apply -f examples/simple-api/app.yml --node node-a --store file://./momo-state
# or: momo apply -f examples/api-with-db/app.yml --node node-a --store file://./momo-state
# Schema demo (placeholder image): examples/momo/app.yml

Or run both roles detached in one shell (momo start / stop / logs / ps — never under systemd):

export MOMO_RUNTIME_DIR=./.momo-runtime
momo start all --store file://./momo-state --node-id node-a
momo logs gateway -f

Published container ports use loopback by default; set --advertise-addr on the node when the gateway must reach backends on another host.

Link a second node

# On host B (shared store required — sqlite on shared disk or postgres):
momo node --node-id node-b --store postgres://… --auto-register \
  --advertise-addr 10.0.0.12
momo apply -f examples/momo/app.yml --node node-b --store postgres://…

See Production for systemd, auth/mTLS, and multi-node layout.

Store backends

URI	Use
file://./momo-state	Local single-process development
sqlite://./momo.db	Single-host multi-process
postgres://…	Multi-host production

Install

Release tarballs (linux/darwin amd64+arm64) and the container image are published from GitHub Actions on v* tags.

make install                 # installs `momo` to $(PREFIX)/bin
make install PREFIX=$HOME/.local
sudo make install-systemd    # Linux: units + /etc/momo/momo.env example
# or: sudo momo service install --all

Building from source:

cargo build --workspace
cargo run -p momo-cli -- --help

Building momo edge needs OpenSSL (Pingora). On macOS with Homebrew:

export OPENSSL_DIR="$(brew --prefix openssl@3)"
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig"

Source and releases: github.com/lalitgehani/momo.