From 3e9f9811cb90baf370a4f6601c31344f3030bd35 Mon Sep 17 00:00:00 2001
From: david-hummingbot <85695272+david-hummingbot@users.noreply.github.com>
Date: Tue, 23 Jun 2026 20:31:57 +0800
Subject: [PATCH] Enhance README with Tailscale and API information

Updated README to include Tailscale setup instructions and API access details.
---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 67 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5561149a..8dc76d6b 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,55 @@
 
 A REST API for managing Hummingbot trading bots across multiple exchanges, with AI assistant integration via MCP.
 
+> **Why we recommend Tailscale for production**
+>
+> Hummingbot API controls real trading: orders, balances, bots, and stored exchange keys. That has always required strong passwords and careful configuration—but **the risk surface has grown**. Tools like **MCP**, **Condor agents**, and other AI assistants make powerful API actions easier to trigger, while cloud VPSes are constantly scanned for open ports like **8000**.
+>
+> **Tailscale is one safeguard you can add**: it puts the API on a private encrypted network so only your devices can reach it, without publishing port 8000 to the internet. It does **not** replace proper security—use strong API and config passwords, keep exchange keys protected, and avoid exposing sensitive services publicly. Tailscale also works when the API and clients run on the **same machine**.
+
 ## Quick Start
 
 **Recommended (Docker):** install from an empty directory with the [Hummingbot Deploy](https://github.com/hummingbot/deploy) helper script. **Docker** must be installed and running first.
 
+### Before you install (production)
+
+For VPS or remote deployments, prepare Tailscale first:
+
+1. Create a free account at [tailscale.com](https://tailscale.com)
+2. Generate a **reusable** auth key at [Settings → Keys](https://login.tailscale.com/admin/settings/keys) (starts with `tskey-auth-`)
+3. Enable **[MagicDNS](https://login.tailscale.com/admin/dns)** in the Tailscale admin console
+
+Full walkthrough: [hummingbot.org Tailscale guide](https://hummingbot.org/hummingbot-api/tailscale/) · [Securing Condor and Hummingbot API with Tailscale](https://hummingbot.org/blog/posts/securing-condor-and-hummingbot-api-with-tailscale/)
+
+### Install
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash -s -- --hummingbot-api
 ```
 
 The script clones **`hummingbot-api`**, runs **`make setup`** (creates **`.env`**), pulls Compose images, and runs **`make deploy`**, which starts the **API**, **PostgreSQL**, and **EMQX** containers.
 
-That's it! The API is now running at http://localhost:8000
+The setup script prompts for:
+
+- **Credentials** — API username/password (HTTP Basic Auth) and config password (encrypts bot credentials)
+- **Tailscale** — answer **`y`** when asked *Use Tailscale for secure private networking?* and paste your auth key (default hostname: **`hummingbot-api`**)
+
+If the script finishes but services did not start, run:
+
+```bash
+cd hummingbot-api
+make setup
+make deploy
+```
+
+### Access the API
+
+| Where you connect from | URL |
+|------------------------|-----|
+| Same machine as the API | `http://localhost:8000` |
+| Another device on your tailnet (Condor, MCP, browser) | `http://hummingbot-api:8000` |
+
+Use your API username and password for all requests. **Do not open port 8000 on your public firewall** when Tailscale is enabled.
 
 | Command | Description |
 |---------|-------------|
@@ -26,28 +64,32 @@ That's it! The API is now running at http://localhost:8000
 
 ## Services
 
-After hummingot-api is running, these services are available:
+After hummingbot-api is running, these services are available:
 
-| Service | URL | Description |
-|---------|-----|-------------|
-| **API** | http://localhost:8000 | REST API |
-| **Swagger UI** | http://localhost:8000/docs | Interactive API documentation |
-| **PostgreSQL** | localhost:5432 | Database |
-| **EMQX** | localhost:1883 | MQTT broker |
-| **EMQX Dashboard** | http://localhost:18083 | Broker admin (admin/public) |
+| Service | Local URL | Tailnet URL (when Tailscale enabled) | Description |
+|---------|-----------|--------------------------------------|-------------|
+| **API** | http://localhost:8000 | http://hummingbot-api:8000 | REST API |
+| **Swagger UI** | http://localhost:8000/docs | http://hummingbot-api:8000/docs | Interactive API documentation |
+| **PostgreSQL** | localhost:5432 | — | Database |
+| **EMQX** | localhost:1883 | — | MQTT broker |
+| **EMQX Dashboard** | http://localhost:18083 | — | Broker admin (admin/public) |
 
 ## Connect AI Assistant (MCP)
 
+> **Production:** use `http://hummingbot-api:8000` (MagicDNS) instead of `localhost` when MCP runs on a different device than the API. Both must be on the same Tailscale account.
+
 ### Claude Code (CLI)
 
 ```bash
 claude mcp add --transport stdio hummingbot -- \
   docker run --rm -i \
-  -e HUMMINGBOT_API_URL=http://host.docker.internal:8000 \
+  -e HUMMINGBOT_API_URL=http://hummingbot-api:8000 \
   -v hummingbot_mcp:/root/.hummingbot_mcp \
   hummingbot/hummingbot-mcp:latest
 ```
 
+For local-only dev on the same machine, use `http://host.docker.internal:8000` instead.
+
 Then use natural language:
 - "Show my portfolio balances"
 - "Set up my Binance account"
@@ -64,7 +106,7 @@ Add to your config file:
   "mcpServers": {
     "hummingbot": {
       "command": "docker",
-      "args": ["run", "--rm", "-i", "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000", "-v", "hummingbot_mcp:/root/.hummingbot_mcp", "hummingbot/hummingbot-mcp:latest"]
+      "args": ["run", "--rm", "-i", "-e", "HUMMINGBOT_API_URL=http://hummingbot-api:8000", "-v", "hummingbot_mcp:/root/.hummingbot_mcp", "hummingbot/hummingbot-mcp:latest"]
     }
   }
 }
@@ -92,6 +134,11 @@ PASSWORD=admin              # API password
 CONFIG_PASSWORD=admin       # Encrypts bot credentials
 DATABASE_URL=...            # PostgreSQL connection
 GATEWAY_URL=...             # Gateway URL (for DEX)
+
+# Tailscale (recommended for production)
+TAILSCALE_ENABLED=true
+TAILSCALE_AUTH_KEY=tskey-auth-...
+TAILSCALE_HOSTNAME=hummingbot-api   # MagicDNS hostname on your tailnet
 ```
 
 Edit `.env` and restart with `make deploy` to apply changes.
@@ -108,6 +155,7 @@ Use this when running on a VPS or cloud server and want to access the API privat
 2. Go to **Settings → Keys**: [tailscale.com/admin/settings/keys](https://tailscale.com/admin/settings/keys)
 3. Click **Generate auth key** — check **Reusable** for multiple deployments
 4. Copy the key (starts with `tskey-auth-`)
+5. Enable **[MagicDNS](https://login.tailscale.com/admin/dns)** in the Tailscale admin console
 
 ### Setup
 
@@ -159,6 +207,12 @@ When `TAILSCALE_ENABLED=true`, `make run` will automatically install Tailscale i
 make tailscale-status
 ```
 
+From another device on your tailnet:
+
+```bash
+curl -u YOUR_USERNAME:YOUR_PASSWORD http://hummingbot-api:8000/health
+```
+
 ## API Features
 
 - **Portfolio**: Balances, positions, P&L across all exchanges
@@ -203,5 +257,7 @@ Confirm the node appears in `tailscale status` and that MagicDNS is enabled in y
 
 ## Support
 
+- **Docs**: https://hummingbot.org/hummingbot-api/
+- **Tailscale guide**: https://hummingbot.org/hummingbot-api/tailscale/
 - **API Docs**: http://localhost:8000/docs
 - **Issues**: https://github.com/hummingbot/hummingbot-api/issues