Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

feat(cli): add BIND_HOST env var to configure listen interface (#488)

W. H. Wang79ee65a610dd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-26
diff --git a/ministack/app.py b/ministack/app.py
index 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_host
with 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 = 75
config.loglevel = LOG_LEVEL.upper()