feat: support configurable HTTP bind host via --host / DBHUB_HOST env

.env.example

@@ -33,6 +33,11 @@ TRANSPORT=stdio
 # Used for both frontend and MCP endpoint (when transport=http)
 PORT=8080
 
+# HTTP bind host (default: 0.0.0.0 — listens on all interfaces)
+# For production, set HOST=127.0.0.1 and front DBHub with a reverse proxy
+# (nginx/Caddy) or a firewall. DBHub does not authenticate HTTP clients.
+# HOST=0.0.0.0
+
 # SSH Tunnel Configuration (optional)
 # Use these settings to connect through an SSH bastion host
 # SSH_HOST=bastion.example.com

README.md

@@ -86,6 +86,14 @@ npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:p
 npx @bytebase/dbhub@latest --transport http --port 8080 --demo
 ```
 
+**Restrict to loopback (recommended for production):**
+
+```bash
+npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --demo
+```
+
+> The HTTP transport defaults to `--host 0.0.0.0`, exposing DBHub on every network interface. For production, bind to `127.0.0.1` and front DBHub with a reverse proxy (nginx/Caddy) or firewall — DBHub does not authenticate HTTP clients.
+
 See [Command-Line Options](https://dbhub.ai/config/command-line) for all available parameters.
 
 ### Multi-Database Setup

docs/config/command-line.mdx

@@ -50,6 +50,27 @@ Command-line flags are passed when starting DBHub. These have the highest priori
   ```
 </ParamField>
 
+### --host
+
+<ParamField path="--host" type="string" env="HOST" default="0.0.0.0">
+  HTTP bind address. Only used when `--transport=http`. Ignored for stdio transport.
+
+  ```bash
+  # Restrict to loopback (recommended for production)
+  npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --dsn "..."
+
+  # Bind to a specific interface
+  npx @bytebase/dbhub@latest --transport http --host 10.0.0.5 --port 8080 --dsn "..."
+
+  # IPv6 loopback
+  npx @bytebase/dbhub@latest --transport http --host ::1 --port 8080 --dsn "..."
+  ```
+
+  <Warning>
+  The default `0.0.0.0` exposes DBHub on every network interface. For production, set `--host 127.0.0.1` and place DBHub behind a reverse proxy (nginx/Caddy) or restrict with a firewall — DBHub does not authenticate HTTP clients.
+  </Warning>
+</ParamField>
+
 ### --dsn
 
 <ParamField path="--dsn" type="string" env="DSN">
@@ -274,6 +295,7 @@ npx @bytebase/dbhub@latest --dsn "..." \
 |------------|---------------------|------|-------------|
 | `--transport` | `TRANSPORT` | string | Transport mode: stdio or http (default: `stdio`) |
 | `--port` | `PORT` | number | HTTP server port (http transport only, default: `8080`) |
+| `--host` | `HOST` | string | HTTP bind address (http transport only, default: `0.0.0.0`) |
 | `--demo` | - | boolean | Use sample employee database |
 | `--id` | `ID` | string | Instance identifier for tool names |
 | `--config` | - | string | Path to TOML config file (default: `./dbhub.toml`) |

src/__tests__/http-bind-host.integration.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn, ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+describe('HTTP bind host integration', () => {
+  let serverProcess: ChildProcess | null = null;
+  let testDbPath: string;
+  const testPort = 3002;
+  const testHost = '127.0.0.1';
+  const startupLogs: string[] = [];
+
+  beforeAll(async () => {
+    testDbPath = path.join(os.tmpdir(), `bind_host_test_${Date.now()}_${Math.random().toString(36).substr(2, 9)}.db`);
+
+    // Invoke tsx directly via node to avoid pnpm.cmd resolution issues on Windows.
+    const tsxCli = path.resolve(process.cwd(), 'node_modules', 'tsx', 'dist', 'cli.mjs');
+    const entry = path.resolve(process.cwd(), 'src', 'index.ts');
+
+    serverProcess = spawn(process.execPath, [tsxCli, entry, '--transport=http'], {
+      env: {
+        ...process.env,
+        DSN: `sqlite://${testDbPath}`,
+        HOST: testHost,
+        PORT: testPort.toString(),
+        NODE_ENV: 'test',
+      },
+      stdio: 'pipe',
+    });
+
+    serverProcess.stdout?.on('data', (data) => {
+      startupLogs.push(data.toString());
+    });
+    serverProcess.stderr?.on('data', (data) => {
+      startupLogs.push(data.toString());
+    });
+
+    // Wait for /healthz to respond on the configured host
+    let ready = false;
+    for (let i = 0; i < 30; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      try {
+        const res = await fetch(`http://${testHost}:${testPort}/healthz`);
+        if (res.status === 200) {
+          ready = true;
+          break;
+        }
+      } catch {
+        // not ready yet
+      }
+    }
+
+    if (!ready) {
+      throw new Error(`Server did not bind to ${testHost}:${testPort} within timeout. Logs:\n${startupLogs.join('')}`);
+    }
+  }, 45000);
+
+  afterAll(async () => {
+    if (serverProcess) {
+      serverProcess.kill('SIGTERM');
+      await new Promise<void>((resolve) => {
+        if (!serverProcess) return resolve();
+        serverProcess.on('exit', () => resolve());
+        setTimeout(() => {
+          if (serverProcess && !serverProcess.killed) serverProcess.kill('SIGKILL');
+          resolve();
+        }, 5000);
+      });
+    }
+    if (testDbPath && fs.existsSync(testDbPath)) {
+      fs.unlinkSync(testDbPath);
+    }
+  });
+
+  it('responds on the configured host', async () => {
+    const res = await fetch(`http://${testHost}:${testPort}/healthz`);
+    expect(res.status).toBe(200);
+  });
+
+  it('logs the actual bound address at startup', () => {
+    const allLogs = startupLogs.join('');
+    expect(allLogs).toContain(`${testHost}:${testPort}`);
+  });
+});

src/config/__tests__/env.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { buildDSNFromEnvParams, resolveDSN, resolveId } from '../env.js';
+import { buildDSNFromEnvParams, resolveDSN, resolveHost, resolveId } from '../env.js';
 
 // Mock toml-loader to prevent it from loading dbhub.toml during tests
 vi.mock('../toml-loader.js', () => ({
@@ -391,4 +391,136 @@ describe('Environment Configuration Tests', () => {
       });
     });
   });
+
+  describe('resolveHost', () => {
+    const originalArgv = process.argv;
+
+    beforeEach(() => {
+      delete process.env.HOST;
+      process.argv = ['node', 'script.js'];
+    });
+
+    afterEach(() => {
+      process.argv = originalArgv;
+    });
+
+    it('defaults to 0.0.0.0 when nothing is set', () => {
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '0.0.0.0', source: 'default' });
+    });
+
+    it('reads HOST from the environment variable', () => {
+      process.env.HOST = '127.0.0.1';
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '127.0.0.1', source: 'environment variable' });
+    });
+
+    it('reads --host from command line arguments (equals form)', () => {
+      process.argv = ['node', 'script.js', '--host=10.0.0.5'];
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '10.0.0.5', source: 'command line argument' });
+    });
+
+    it('reads --host from command line arguments (space form)', () => {
+      process.argv = ['node', 'script.js', '--host', '192.168.1.10'];
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '192.168.1.10', source: 'command line argument' });
+    });
+
+    it('prefers --host over HOST environment variable', () => {
+      process.env.HOST = '0.0.0.0';
+      process.argv = ['node', 'script.js', '--host=127.0.0.1'];
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '127.0.0.1', source: 'command line argument' });
+    });
+
+    it('treats empty HOST env var as unset and falls back to default', () => {
+      process.env.HOST = '';
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '0.0.0.0', source: 'default' });
+    });
+
+    it('accepts IPv6 addresses verbatim', () => {
+      process.env.HOST = '::1';
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: '::1', source: 'environment variable' });
+    });
+
+    it('exits when --host is provided without a value', () => {
+      process.argv = ['node', 'script.js', '--host'];
+      const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`process.exit: ${code}`);
+      }) as never);
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      expect(() => resolveHost()).toThrow('process.exit: 1');
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--host requires a value'));
+
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('exits when --host is followed by another flag', () => {
+      process.argv = ['node', 'script.js', '--host', '--port=8080'];
+      const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`process.exit: ${code}`);
+      }) as never);
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      expect(() => resolveHost()).toThrow('process.exit: 1');
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--host requires a value'));
+
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('passes through an explicit --host=true without erroring (node listen will reject it)', () => {
+      process.argv = ['node', 'script.js', '--host=true'];
+
+      const result = resolveHost();
+
+      expect(result).toEqual({ host: 'true', source: 'command line argument' });
+    });
+
+    it('exits when --host= is provided with an empty value', () => {
+      process.argv = ['node', 'script.js', '--host='];
+      const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`process.exit: ${code}`);
+      }) as never);
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      expect(() => resolveHost()).toThrow('process.exit: 1');
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--host requires a value'));
+
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('exits when --host= is followed by another flag', () => {
+      process.argv = ['node', 'script.js', '--host=', '--port=8080'];
+      const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`process.exit: ${code}`);
+      }) as never);
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      expect(() => resolveHost()).toThrow('process.exit: 1');
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--host requires a value'));
+
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+  });
 });

src/config/env.ts

@@ -333,6 +333,61 @@ export function resolvePort(): { port: number; source: string } {
   return { port: 8080, source: "default" };
 }
 
+/**
+ * Resolve HTTP bind host from command line args or environment variables.
+ * Returns the host with "0.0.0.0" as the default (listen on all interfaces).
+ *
+ * Note: Only applicable when using --transport=http. Default "0.0.0.0" keeps
+ * backward compatibility; production deployments should set "127.0.0.1" and
+ * front DBHub with a reverse proxy or firewall.
+ */
+export function resolveHost(): { host: string; source: string } {
+  // Detect a missing --host value directly in argv. parseCommandLineArgs()
+  // collapses bare flags and explicit empty values into the same sentinel
+  // string "true", which is indistinguishable from an explicit --host=true.
+  // We inspect argv here so we can reject only the genuinely value-less cases:
+  //   --host            (followed by nothing or another --flag)
+  //   --host=           (empty after equals, alone or followed by another --flag)
+  // An explicit --host=true passes through and fails later at listen().
+  const rawArgs = process.argv.slice(2);
+  for (let i = 0; i < rawArgs.length; i++) {
+    const token = rawArgs[i];
+
+    if (token === "--host") {
+      const next = rawArgs[i + 1];
+      if (!next || next.startsWith("--")) {
+        console.error("ERROR: --host requires a value (e.g., --host=127.0.0.1).");
+        process.exit(1);
+      }
+      break;
+    }
+
+    if (token === "--host=") {
+      const next = rawArgs[i + 1];
+      if (!next || next.startsWith("--")) {
+        console.error("ERROR: --host requires a value (e.g., --host=127.0.0.1).");
+        process.exit(1);
+      }
+      break;
+    }
+  }
+
+  const args = parseCommandLineArgs();
+
+  // 1. Command line argument has highest priority
+  if (args.host) {
+    return { host: args.host, source: "command line argument" };
+  }
+
+  // 2. Environment variable (empty string is treated as unset)
+  if (process.env.HOST) {
+    return { host: process.env.HOST, source: "environment variable" };
+  }
+
+  // 3. Default: bind all interfaces
+  return { host: "0.0.0.0", source: "default" };
+}
+
 /**
  * Redact sensitive information from a DSN string
  * Replaces the password with asterisks