Skip to content

Enhance README with Tailscale and API information #184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
david-hummingbot wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Enhance README with Tailscale and API information #184

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 67 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---------|-------------|
Expand All @@ -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"
Expand All @@ -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"]
}
}
}
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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