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,86 @@ 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();
+    });
+  });
 });

src/config/env.ts

@@ -333,6 +333,36 @@ 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 } {
+  const args = parseCommandLineArgs();
+
+  // 1. Command line argument has highest priority.
+  //    parseCommandLineArgs turns bare --host (no value) into "true"; reject it.
+  if (args.host) {
+    if (args.host === "true") {
+      console.error("ERROR: --host requires a value (e.g., --host=127.0.0.1).");
+      process.exit(1);
+    }
+    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

src/server.ts

@@ -8,7 +8,7 @@ import { fileURLToPath } from "url";
 
 import { ConnectorManager } from "./connectors/manager.js";
 import { ConnectorRegistry } from "./connectors/interface.js";
-import { resolveTransport, resolvePort, resolveSourceConfigs, isDemoMode } from "./config/env.js";
+import { resolveTransport, resolvePort, resolveHost, resolveSourceConfigs, isDemoMode } from "./config/env.js";
 import { registerTools } from "./tools/index.js";
 import { listSources, getSource } from "./api/sources.js";
 import { listRequests } from "./api/requests.js";
@@ -129,8 +129,9 @@ See documentation for more details on configuring database connections.
     // Resolve transport type (for MCP server)
     const transportData = resolveTransport();
 
-    // Resolve port for HTTP server (only needed for http transport)
+    // Resolve port and host for HTTP server (only needed for http transport)
     const port = transportData.type === "http" ? resolvePort().port : null;
+    const host = transportData.type === "http" ? resolveHost().host : null;
 
     // Print ASCII art banner with version and slogan
     // Collect active modes
@@ -258,17 +259,32 @@ See documentation for more details on configuring database connections.
       }
 
       // Start the HTTP server
-      app.listen(port, '0.0.0.0', () => {
+      const httpServer = app.listen(port!, host!, () => {
+        const address = httpServer.address();
+        const boundHost = typeof address === 'object' && address ? address.address : host!;
+        const boundPort = typeof address === 'object' && address ? address.port : port!;
+        const displayHost = boundHost.includes(':') ? `[${boundHost}]` : boundHost;
+        // Wildcard binds (0.0.0.0 / ::) are not routable; use localhost for user URLs.
+        const userHost = (boundHost === '0.0.0.0' || boundHost === '::') ? 'localhost' : displayHost;
+
+        console.error(`HTTP server listening on ${displayHost}:${boundPort}`);
+
         // In development mode, suggest using the Vite dev server for hot reloading
         if (process.env.NODE_ENV === 'development') {
           console.error('Development mode detected!');
           console.error('   Workbench dev server (with HMR): http://localhost:5173');
-          console.error('   Backend API: http://localhost:8080');
+          console.error(`   Backend API: http://${userHost}:${boundPort}`);
           console.error('');
         } else {
-          console.error(`Workbench at http://localhost:${port}/`);
+          console.error(`Workbench at http://${userHost}:${boundPort}/`);
         }
-        console.error(`MCP server endpoint at http://localhost:${port}/mcp`);
+        console.error(`MCP server endpoint at http://${userHost}:${boundPort}/mcp`);
+      });
+
+      httpServer.on('error', (err) => {
+        const displayHost = host!.includes(':') ? `[${host!}]` : host!;
+        console.error(`Failed to bind HTTP server to ${displayHost}:${port}: ${err.message}`);
+        process.exit(1);
       });
     } else {
       // STDIO transport: Pure MCP-over-stdio, no HTTP server