monolith-engine

███╗   ███╗ ██████╗ ███╗   ██╗ ██████╗ ██╗     ██╗████████╗██╗  ██╗
████╗ ████║██╔═══██╗████╗  ██║██╔═══██╗██║     ██║╚══██╔══╝██║  ██║
██╔████╔██║██║   ██║██╔██╗ ██║██║   ██║██║     ██║   ██║   ███████║
██║╚██╔╝██║██║   ██║██║╚██╗██║██║   ██║██║     ██║   ██║   ██╔══██║
██║ ╚═╝ ██║╚██████╔╝██║ ╚████║╚██████╔╝███████╗██║   ██║   ██║  ██║
╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚═╝   ╚═╝   ╚═╝  ╚═╝

YOUR SERVER. NO MIDDLEMEN.

A self-hosted deployment control plane — git push, zero-downtime deploys, databases, and rollbacks — running on a server you own, at your server's price, not platform egress pricing.

📍 Current status: early access, single-maintainer project. The core deploy/rollback/database pipeline is real and working (see Features). TLS is not wired up yet — don't put secrets over plaintext production traffic. There's no uptime SLA or on-call support. If that's fine for your use case, welcome aboard. Details in Known Limitations.

Table of Contents

• Why Monolith
• Quick Start
• Installation
• Features
• Command Reference
• Monolith vs. the alternatives
• Known Limitations
• Roadmap
• Contributing
• License

🔥 Why Monolith

Platforms like Vercel price bandwidth at a steep multiple over what it costs on a plain VPS — commonly cited around $0.15/GB in overages, versus roughly $1/TB-equivalent on something like Hetzner. That's invisible on a small app. It stops being invisible the moment your app serves real media, runs an AI generation pipeline, or just has a good week and gets a traffic spike — at which point "surprise $700 bill" and "surprise $23,000 bill" are both things that have actually happened to real people, not hypotheticals.

Monolith doesn't try to be a bigger, better Vercel. It's the thing you point at a server you already have — a $5 VPS, a spare machine, whatever — and get back a real deploy pipeline: git push to ship, instant rollback when something breaks, databases with one command, without needing to hire a devops engineer or learn Coolify's full surface area to get there.

⚡ Quick Start

# 1. Install the CLI
npm i monolith-engine

# 2. Get a Personal Access Token from your Monolith dashboard, then log in
monolith login --token <YOUR_PAT> --url <YOUR_DASHBOARD_URL>

# 3. Register a server you own (name, public IP, agent key)
monolith server:add

# 4. Initialize your project and tether it to that server
monolith init my-app

# 5. Ship it
monolith deploy

Every git push after that redeploys automatically if you run monolith github:connect once.

Run monolith guide at any point for a full interactive walkthrough with a command-by-command failure-diagnostics reference — it's built into the CLI itself.

📦 Installation

npm i monolith-engine

Requires Node 18+ and a server you can SSH into (any provider — Hetzner, DigitalOcean, a home server, whatever you've got).

✨ Features

• 🚀 Git-push deploys — connect a GitHub repo once, then every push ships automatically
• 🔁 Zero-downtime blue/green deploys — new container has to pass a health check before traffic switches to it
• ⏪ Instant rollback — revert to the previous working deployment with one command, no rebuild
• 🗄️ One-command databases — Postgres, MySQL, Redis, or MongoDB, provisioned and auto-linked into your project's vault
• 🔒 Encrypted secrets vault — environment variables stored server-side, not in your repo
• 🌐 Bring-your-own-server — works on any machine with a public IP; no per-provider integration required
• 📡 Live log streaming — tail build output or runtime logs straight from your terminal
• 🧭 Built-in interactive guide — monolith guide walks through setup and diagnoses failures per command

📖 Command Reference

monolith login — authenticate the CLI with your account

monolith login --token <PAT> --url <YOUR_DASHBOARD_URL>

Generates a Personal Access Token on your web dashboard first (Settings → Personal Access Tokens), then stores it locally in ~/.monolith/auth.json. Every other command reads this file automatically — you only do this once per machine.

monolith server:add — register a server you own

monolith server:add

Interactive prompt for a name, public IPv4 address, and the agent's API key. This is what makes Monolith bring-your-own-cloud — no provider-specific integration, just an IP.

monolith init <project-name> — set up a project

monolith init my-app

Detects your framework, injects any needed build scripts, and lets you tether the project to one of your registered servers.

monolith deploy — ship the current directory

monolith deploy

Packs the project, uploads it to the tethered server, and runs a health-checked blue/green traffic switch. No downtime if the new container passes its health check; nothing changes if it doesn't.

monolith rollback — undo the last deploy

monolith rollback

Flips traffic back to the previous container instantly. No rebuild.

monolith db:create <name> — provision a database

monolith db:create <db_Name>

Choose Postgres, MySQL, Redis, or MongoDB. The connection string is auto-injected into your project's secrets vault.

monolith env:set / env:rm — manage secrets

monolith env:set
monolith env:rm

Interactively add or remove environment variables in the remote vault. Redeploy afterward for changes to take effect.

monolith github:connect — automatic deploy on push

monolith github:connect

Registers a webhook on your GitHub repo pointing at your tethered server. Requires a GitHub PAT with repo and admin:repo_hook scopes.

monolith list / status / logs — see what's running

monolith list      # quick table of apps and databases
monolith status     # full diagnostic: containers, vault, rollback targets, db health
monolith logs        # stream build or runtime logs live

monolith destroy / app:purge / db:destroy — tear things down

monolith destroy [project-id]        # delete a project and everything on it
monolith app:purge [container-name]  # remove just the app container, keep the db
monolith db:destroy <container-name> # delete a specific database

All three require typing an exact confirmation string — intentional, not a bug, so a fat-fingered Enter can't delete production.

monolith guide — interactive walkthrough

monolith guide

An animated, in-terminal guide covering login, the full pipeline, and an expandable command reference with likely failure reasons for every command above. Type a command name or number to expand it, q to exit.

⚖️ Monolith vs. the alternatives

	Monolith	Vercel / Railway	Coolify
Runs on	Your own server	Their infrastructure	Your own server
Pricing model	Flat, no usage-based egress	Usage-based (bandwidth, functions)	Free (self-managed)
Setup	CLI-first, a few commands	Instant, zero setup	Full web dashboard, more surface area
Ops burden	You manage the box, Monolith manages the deploy	None — fully managed	You manage everything
Execution model	Always-on containers, no timeout	Serverless functions, execution limits	Always-on containers
Best fit	Devs who already have a server and want git-push simplicity without learning a full platform	Teams who want zero infrastructure thinking and can absorb usage pricing	Teams comfortable owning the whole self-hosting stack

Coolify is free, mature, and does more than Monolith does today — if you want the full self-hosted platform experience and don't mind managing it, it's a genuinely good option. Monolith exists for the narrower case: you want the git-push-and-forget experience without becoming your own devops team.

⚠️ Known Limitations

Being upfront about this matters more than looking finished:

• No TLS yet. Traffic between the CLI and your server isn't encrypted in transit. Don't run sensitive production workloads on this until that's resolved.
• No horizontal scaling / replicas yet. One container per project — a real traffic spike will bottleneck it.
• Single point of failure. Control plane and deploy target currently share infrastructure in most setups.

None of these are secret — they're the current top-of-list priorities.

🗺️ Roadmap

• TLS everywhere
• Load-balanced replicas per project (Caddy already supports this — config change, not a rewrite)
• Control-plane / data-plane separation
• Web dashboard (in progress)
• Real multi-user accounts and billing

🤝 Contributing

This is early and small. Issues and PRs are welcome, but please open an issue to discuss first for anything beyond a small fix — the roadmap above is the current source of truth for direction.

📄 License

MIT — see LICENSE.

Let's deploy your dream project.