Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
feat(cli): add BIND_HOST env var to configure listen interface (#488)
W. H. Wang79ee65a610dd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e2066936..96f28b1d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,13 @@ All notable changes to MiniStack will be documented here.Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).Versioning follows [Semantic Versioning](https://semver.org/).+---++## [Unreleased]++### Added+- **`BIND_HOST` env var to configure the listen interface** — the bind interface was previously hard-coded to `0.0.0.0` (no env var, no CLI flag). Setting `BIND_HOST=127.0.0.1 ministack` now restricts MiniStack to loopback (useful on shared dev machines or when a `pip install` user wants tighter network exposure). Defaults to `0.0.0.0`, so existing setups behave identically. Distinct from `MINISTACK_HOST` (the *virtual* hostname used for S3 virtual-host / execute-api URL matching) — `BIND_HOST` is the TCP listen interface only. Docker users can keep using `docker run -p 127.0.0.1:4566:4566 …` as before; this is for the `pip install ministack` path.+---## [1.3.15] — 2026-04-26diff --git a/ministack/app.py b/ministack/app.pyindex 98c97579..bb8da023 100644--- a/ministack/app.py+++ b/ministack/app.py@@ -1379,6 +1379,10 @@ def main():args = parser.parse_args()port = int(_resolve_port())+ # BIND_HOST controls the bind interface; defaults to 0.0.0.0 (existing+ # behaviour). Distinct from MINISTACK_HOST, which is the virtual hostname+ # used for S3 virtual-host / execute-api URL matching.+ bind_host = os.environ.get("BIND_HOST", "0.0.0.0")if args.stop:pf = _pid_file(port)@@ -1395,9 +1399,12 @@ def main():os.remove(pf)return+ # 0.0.0.0 binds every interface so 127.0.0.1 always works as a probe;+ # for an explicit BIND_HOST, probe that host directly.+ probe_host = "127.0.0.1" if bind_host == "0.0.0.0" else bind_hostwith socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:- if s.connect_ex(("127.0.0.1", port)) == 0:- print(f"ERROR: Port {port} is already in use. Is MiniStack already running?\n"+ if s.connect_ex((probe_host, port)) == 0:+ print(f"ERROR: {probe_host}:{port} is already in use. Is MiniStack already running?\n"f" Stop it with: ministack --stop\n"f" Or use a different port: GATEWAY_PORT=4567 ministack")raise SystemExit(1)@@ -1411,7 +1418,7 @@ def main():log_fh = open(log_file, "w")proc = subprocess.Popen([sys.executable, "-m", "hypercorn", "ministack.app:app",- "--bind", f"0.0.0.0:{port}",+ "--bind", f"{bind_host}:{port}","--log-level", LOG_LEVEL.upper(),"--keep-alive", "75"],stdout=log_fh,@@ -1450,7 +1457,7 @@ def main():logging.getLogger("hypercorn.access").addFilter(_HealthLogFilter())config = HypercornConfig()- config.bind = [f"0.0.0.0:{port}"]+ config.bind = [f"{bind_host}:{port}"]config.keep_alive_timeout = 75config.loglevel = LOG_LEVEL.upper()