Mission Briefing¶

Platforms want you to pay per process. Heroku charges per dyno. AWS bills per container. Foreman needs Ruby. PM2 needs Node. systemd needs… systemd.

FreeBSD doesn’t have Docker. Alpine uses OpenRC. Your Go binary shouldn’t require Ruby just to supervise it.

Mothership liberates you from runtime dependencies and platform billing models.

Why Mothership?¶

• Single Binary: No Ruby, Node, or systemd required
• Platform-Agnostic: Same config for Heroku, AWS, bare metal, FreeBSD
• One Process: Platforms see one dyno/container, you run multiple services
• Built-In Proxy: HTTP/WebSocket routing without nginx
• FreeBSD Native: Works where Docker doesn’t exist

The Liberation Process¶

Phase 1: Install¶

cargo install mothership

# Or download binary
curl -L https://github.com/seuros/mothership/releases/latest/download/mothership-$(uname -s)-$(uname -m).tar.gz | tar xz

No runtime dependencies. Works on Linux, FreeBSD, macOS.

Phase 2: Configuration¶

One config replaces Procfile, systemd units, nginx configs, and docker-compose.yml:

# ship-manifest.toml
[mothership.bind]
http = "0.0.0.0:8080"

# Migrations run before ships start
[[mothership.prelaunch]]
name = "migrations"
command = "bundle exec rails db:migrate"

# Web server
[[fleet.web]]
name = "app"
command = "bundle exec puma"
routes = [{ bind = "http", pattern = "/.*" }]
healthcheck = "/health"

# Background workers
[[fleet.workers]]
name = "workers"
command = "bundle exec good_job"
depends_on = ["app"]

Phase 3: Deploy Anywhere¶

Heroku (one dyno instead of three):

mothership  # They see one process, you run three

Bare Metal:

mothership  # Same config, zero changes

FreeBSD Jail:

mothership  # Works where Docker doesn't

Platform Cost Comparison¶

Traditional Deployment¶

• Heroku: $7/month per dyno × 3 (web + worker + scheduler) = $21/month
• AWS ECS: $0.05/hour per task × 3 = ~$108/month
• Supervisor: Foreman (needs Ruby), PM2 (needs Node), systemd (needs Linux)

Mothership Deployment¶

• Heroku: $7/month × 1 dyno = $7/month
• AWS ECS: $0.05/hour × 1 task = ~$36/month
• Supervisor: Static binary, no runtime

Savings: 66% on Heroku, 66% on AWS, zero runtime overhead

Advanced Features¶

User-Agent Routing¶

Serve markdown to LLMs, full app to browsers, static cache to bots:

[[fleet.web]]
name = "app"
routes = [{ pattern = "/.*", ua_filter = "browser" }]

[[fleet.web]]
name = "markdown-api"
routes = [{ pattern = "/.*", ua_filter = "llm" }]

HTTP Fingerprinting¶

Ja4H fingerprints detect headless browsers even when they spoof User-Agent.

CORS Preflight Cache¶

Cache OPTIONS requests. 100k+ requests/day → cached once per unique request.

Prometheus Metrics¶

Built-in telemetry at /metrics. No separate exporter needed.

Multi-Server Coordination¶

PostgreSQL advisory locks coordinate migrations across servers:

[mothership.flagship]
enabled = true
election = "postgres"
election_url = "$DATABASE_URL"

Server 1 runs migrations. Servers 2-3 wait. No Consul. No etcd.

Common Objections Debunked¶

“Heroku’s best practice is one process per dyno!” Best practice for their billing, not your wallet.

“What about separation of concerns?” Processes still separate. Just managed by one supervisor instead of three dynos.

“systemd is standard!” FreeBSD doesn’t have it. Alpine uses OpenRC. “Standard” Linux isn’t universal.

“I need Docker!” No you don’t. You need process isolation. Mothership provides that without containers.

Migration Path¶

1. Test locally: Replace Foreman with Mothership
2. Deploy to staging: Same config on staging server
3. Consolidate production: Reduce dyno/container count
4. FreeBSD migration: Move workloads to FreeBSD if desired

No platform lock-in. Same config everywhere.

The Freedom Stack¶

Mothership pairs with:

• Blackship: FreeBSD jail orchestration (container-level isolation)
• PostgreSQL: Database without vendor lock-in
• Caddy/nginx: External reverse proxy if needed
• FreeBSD: OS without corporate capture

Performance Metrics¶

• Binary Size: ~10MB (no TUI/WASM), ~19MB (full features)
• Memory: <50MB resident for typical deployment
• Startup: Sub-second for most configurations
• Throughput: Handles thousands of requests/second

Resources¶

• GitHub Repository
• Documentation
• Blog Post: One Process, Multiple Services
• Blackship (Jail Orchestration)

Built On¶

Mothership uses Rama for the proxy layer. All credit to Glen and the Rama team for building production-ready proxy infrastructure.

---

“The best platform is the one that doesn’t tell you how to deploy.”