Skip to content

Manifest Reference

ship-manifest.toml is the single configuration file for a fleet. This page lists every section; the concept pages cover behavior in depth.

[mothership] # global settings
[mothership.bind] # named external listeners
[[mothership.static_dirs]] # static file serving
[[mothership.uplinks]] # pre-flight dependency checks
[[mothership.prelaunch]] # setup jobs before launch
[mothership.flagship] # multi-server coordination
[mothership.cors_cache] # CORS preflight cache
[mothership.rate_limiting] # optional rate limiting
[base.ship] # template inherited by all ships
[base.bay] # template inherited by all bays
[base.module] # template inherited by all modules
[[fleet.GROUP]] # ships, grouped by name of your choice
[[bays.BAYTYPE]] # bays (docking protocol)
[[modules]] # WASM payloads

A .env file next to the manifest is loaded before parsing; existing process environment variables are never overridden. $VAR expansion works in binds, env values, uplink URLs, and election settings.

Key Type Default Description
metrics_port u16 off Prometheus metrics + /health port
compression bool false gzip/deflate/brotli response compression
cors_cache bool/table false CORS preflight cache (see Routing)

Any key name maps to a listener address:

[mothership.bind]
http = "0.0.0.0:80"
https = { addr = "0.0.0.0:443", proxy_protocol = true }
admin = "unix:///tmp/admin.sock"

See Routing.

Key Type Default Description
path string required Local directory
prefix string – URL prefix (longest prefix wins, falls through to routes)
bind string all binds Limit serving to one bind
Key Type Default Description
url string required postgres://, mysql://, redis://, memgraph://, neo4j://, http(s)://, or tcp://
name string required Name used in logs/errors
timeout string "5s" Connection timeout

See Prelaunch & Uplinks.

Key Type Default Description
name string required Unique identifier
command string required Command to execute
args string[] [] Arguments
env table {} Environment variables
depends_on string[] [] Prelaunch jobs to wait for
Key Type Default Description
enabled bool false Enable flagship coordination
election string "static" "static" or "postgres"
app_name string – Election namespace (required for postgres)
election_url string – PostgreSQL URL
static_flagship string/table – "$VAR" or { command, equals }
prelaunch_timeout u64 300 Seconds escorts wait
election_timeout u64 30 Seconds to acquire the lock

See Flagship.

Key Type Default Description
global_rps f64 unlimited Global requests per second
per_ip_rpm f64 unlimited Per-IP requests per minute
Key Type Default Description
name string required Unique identifier (ASCII, no spaces)
command string required Command to execute
args string[] [] Arguments
cwd string inherited Working directory
bind string – tcp://host:port, unix:///path, or port
healthcheck string – Health check path
healthcheck_initial_delay u64 30 Seconds before the first check
routes array [] Routes (see below)
depends_on string[] [] Ships/bays to wait for
env table {} Environment variables
critical bool true Crash kills the fleet
oneshot bool false Run once and exit
tags string[] [] Tags for --only / --except

Same as ships minus bind/healthcheck/oneshot, plus:

Key Type Default Description
config table {} Config delivered via the docking protocol

See Bays.

Key Type Default Description
bind string required A key from [mothership.bind]
pattern string required Regex matched against the path
strip_prefix string – Prefix removed before forwarding
ua_filter string – browser, chromium, firefox, safari, llm, bot, or ~regex

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

Key Type Default Description
name string required Unique identifier
wasm string required Path to .wasm file
routes string[] [] Regex patterns
phase string "request" request or response
config table {} String key-value config
tags string[] [] Tags for filtering

See WASM Payloads.

[base.ship], [base.bay], and [base.module] provide defaults inherited by every ship, bay, and module respectively. Scalar values are overridable per entry; tags are merged:

[base.ship]
env = { RAILS_ENV = "production" }
critical = true
tags = ["ruby"]
[[fleet.web]]
name = "app"
command = "ruby"
tags = ["web"] # effective: ["ruby", "web"]