mothership 0.0.30

Process supervisor with HTTP exposure - wrap, monitor, and expose your fleet
Documentation
mothership-0.0.30 has been yanked.

Mothership

Process supervisor with HTTP exposure. Launches your fleet, routes traffic, runs WASM plugins.

Features

  • Fleet Management: Launch and monitor ships and bays with dependency ordering
  • Uplinks: Pre-flight connectivity checks for external dependencies (databases, caches)
  • Bays (Docking Protocol): WebSocket multiplexing over Unix sockets for real-time apps
  • Named Binds: Multiple listeners (http, https, ws) routed via TCP or Unix sockets
  • Static File Serving: Serve static assets with configurable path prefix
  • Response Compression: Automatic gzip/deflate/br compression
  • Health Checks: HTTP-based monitoring with circuit breakers
  • Crash Loop Protection: Exponential backoff for failing ships
  • TUI Dashboard: Real-time fleet status with logs (--tui)
  • WASM Payloads: Request/response processing with sandboxing
  • Prometheus Metrics: Ship status, restarts, request counts at /metrics
  • Tag Filtering: --only web or --except workers for selective launching
  • Base Templates: Reduce config duplication
  • Graceful Shutdown: Dependency-aware termination

Installation

cargo install mothership

Or from source:

git clone https://github.com/seuros/mothership.git
cd mothership
cargo build --release

Quick Start

# Initialize a new manifest
mothership init

# Validate configuration
mothership clearance

# View routing chart
mothership chart

# Run the fleet
mothership

# Run with TUI dashboard
mothership --tui

Configuration

Create ship-manifest.toml:

# Global configuration
[mothership]
metrics_port = 9090
compression = true

# Static files (served before routing to ships, with fallthrough)
# Longest prefix wins; if file not found, falls through to routes
[[mothership.static_dirs]]
path = "./public"
prefix = "/static"

# Named binds - external listeners
[mothership.bind]
http = "0.0.0.0:80"
https = "0.0.0.0:443"
ws = "0.0.0.0:8080"

# Web ships
[[fleet.web]]
name = "app"
command = "ruby"
args = ["app.rb"]
bind = "tcp://127.0.0.1:3000"
healthcheck = "/health"
routes = [
  { bind = "http", pattern = "/.*" },
  { bind = "https", pattern = "/.*" },
]

# Background workers
[[fleet.workers]]
name = "sidekiq"
command = "bundle"
args = ["exec", "sidekiq"]
critical = false

# One-shot jobs
[[fleet.jobs]]
name = "migrate"
command = "rails"
args = ["db:migrate"]
oneshot = true

# Docked bays (WebSocket multiplexing)
[[bays.websocket]]
name = "orbitcast"
command = "./orbitcast"
routes = [{ bind = "ws", pattern = "/ws" }]
config = { redis_url = "redis://localhost:6379" }

# WASM payloads (optional)
[[modules]]
name = "rate_limiter"
wasm = "./modules/rate_limiter.wasm"
routes = ["/api/.*"]
phase = "request"

Ships vs Bays

Ships are traditional processes that bind to a port (TCP or Unix socket). Mothership proxies HTTP/WebSocket traffic to them.

Bays use the docking protocol for WebSocket multiplexing. Multiple client connections are multiplexed over a single Unix socket. Ideal for:

  • Real-time apps (chat, notifications)
  • Reducing connection overhead
  • Processes that don't need their own HTTP server

Ship Configuration

Field Type Default Description
name string required Unique identifier (ASCII only, no spaces)
command string required Command to execute
args string[] [] Command arguments
bind string - Internal bind address (tcp://host:port or unix:///path)
healthcheck string - Health check endpoint path
routes array [] HTTP routes (see below)
depends_on string[] [] Ships/bays to wait for before starting
env table {} Environment variables
critical bool true Crash kills entire fleet
oneshot bool false Run once and exit
tags string[] [] Tags for filtering (--only, --except)

Bay Configuration

Field Type Default Description
name string required Unique identifier (ASCII only, no spaces)
command string required Command to execute
args string[] [] Command arguments
routes array [] WebSocket routes
depends_on string[] [] Ships/bays to wait for
env table {} Environment variables
config table {} Config passed via docking protocol
critical bool true Crash kills entire fleet
tags string[] [] Tags for filtering

Route Configuration

Routes map mothership binds to ships/bays:

# Object format
routes = [
  { bind = "http", pattern = "/api/.*" },
  { bind = "ws", pattern = "/cable" },
]

# Shorthand format
routes = ["http:/api/.*", "ws:/cable"]

# With path stripping
routes = [
  { bind = "http", pattern = "/api/.*", strip_prefix = "/api" },
]

Bind Formats

# TCP with explicit prefix
bind = "tcp://127.0.0.1:3000"

# TCP without prefix
bind = "0.0.0.0:8080"

# Port only (defaults to 127.0.0.1)
bind = "3000"

# Unix socket
bind = "unix:///tmp/app.sock"

Docking Protocol

Bays communicate with mothership via Unix sockets using a binary protocol:

Message Direction Purpose
Dock Bay → Mothership Bay ready, sends version
Moored Mothership → Bay Docking confirmed, sends config
Boarding Mothership → Bay New WebSocket client connected
Disembark Mothership → Bay Client disconnected
Cargo Bidirectional WebSocket data payload

Environment variables provided to bays:

  • MS_PID - Mothership process ID
  • MS_SHIP - Bay name
  • MS_SOCKET_DIR - Socket directory
  • MS_SOCKET_PATH - Full socket path
  • MS_BAY_TYPE - Bay type (e.g., "websocket")

Commands

# Run fleet (default)
mothership
mothership run
mothership run -c /path/to/manifest.toml

# Run with TUI
mothership --tui

# Filter by tags
mothership --only web
mothership --only web,api
mothership --except workers

# Pre-flight check (validate + verify uplinks)
mothership preflight

# View routing chart
mothership chart

# Validate manifest (no network access)
mothership clearance

# Initialize new manifest
mothership init

Base Templates

Reduce duplication with base templates:

[base.ship]
env = { RAILS_ENV = "production" }
critical = true
tags = ["ruby"]

[base.bay]
critical = true
tags = ["realtime"]

[base.module]
phase = "request"
tags = ["security"]

# Ships inherit from base.ship
[[fleet.web]]
name = "app"
command = "ruby"
tags = ["web"]  # Combined: ["ruby", "web"]

# Bays inherit from base.bay
[[bays.websocket]]
name = "orbitcast"
command = "./orbitcast"

TUI Dashboard

The TUI shows real-time fleet status:

  • Overview Tab: Ship/bay status, group, PID, health, routes
  • Logs Tab: Per-process stdout/stderr with scroll
  • Modules Tab: WASM payload status

Controls:

  • Tab - Switch tabs
  • ↑/↓ - Navigate ships
  • PgUp/PgDn - Scroll logs
  • q - Quit

WASM Payloads

Payloads process requests/responses at the proxy layer:

[[modules]]
name = "auth"
wasm = "./modules/auth.wasm"
routes = ["/admin/.*"]
phase = "request"

[[modules]]
name = "cache"
wasm = "./modules/cache.wasm"
routes = ["/api/.*"]
phase = "response"
config = { ttl = "3600" }

Payloads can:

  • Block requests (return custom status/body)
  • Modify request path/headers
  • Modify response headers

Static Files & Compression

Static File Serving

Multiple static directories can be configured. Longest prefix wins, with implicit fallthrough to routes if file not found.

# Specific assets directory
[[mothership.static_dirs]]
path = "./public/assets"
prefix = "/assets"

# Catch-all for other static files (with fallthrough to routes)
[[mothership.static_dirs]]
path = "./public"
prefix = "/"
bind = "http"  # Optional: limit to specific bind

Response Compression

[mothership]
compression = true

Supports gzip, deflate, and brotli based on Accept-Encoding.

Environment Variables

Ships and bays inherit environment variables from mothership:

MASTER_KEY=secret DATABASE_URL=postgres://... mothership run

Process-specific env vars override inherited values:

[[fleet.web]]
name = "app"
command = "ruby"
env = { RAILS_ENV = "production" }

Uplinks

Verify external dependencies are reachable before launching the fleet. If any uplink fails, mothership aborts startup.

[[mothership.uplinks]]
url = "postgres://localhost:5432/mydb"
name = "postgres"

[[mothership.uplinks]]
url = "$DATABASE_URL"  # env var expansion
name = "primary-db"
timeout = "10s"  # default: 5s

[[mothership.uplinks]]
url = "redis://cache.internal:6379"
name = "redis"

Pre-flight Command

mothership preflight

Validates the manifest and verifies all uplinks are reachable.

Note: preflight requires network access to the configured uplinks. Running it on your local machine may fail if uplinks are only accessible from the deployment environment (e.g., internal databases, VPC-only services). Use clearance for offline manifest validation.

Supported Schemes

Scheme Default Port Check
postgres://, postgresql:// 5432 TCP
mysql:// 3306 TCP
redis:// 6379 TCP
memgraph://, neo4j:// 7687 TCP
http://, https:// 80/443 HTTP GET
tcp:// required TCP

Deduplication

Uplinks with the same host:port are checked only once:

# These two share the same postgres server - only one TCP check
[[mothership.uplinks]]
url = "postgres://localhost:5432/app_production"
name = "primary"

[[mothership.uplinks]]
url = "postgres://localhost:5432/app_replica"
name = "replica"

Metrics

Enable Prometheus metrics:

[mothership]
metrics_port = 9090

Scrape http://127.0.0.1:9090/metrics:

mothership_ship_status{ship="app",group="web"} 1
mothership_ship_healthy{ship="app",group="web"} 1
mothership_ship_restarts_total{ship="app",group="web"} 0
mothership_requests_total{route="/api"} 1234
mothership_fleet_ships_total 3

Also serves /health for liveness probes.

License

MIT