hummingbot-developer
Developer workflow skill for building and running the full Hummingbot stack from source.
Commands
(run as
/hummingbot-developer
check only, don't install anything
--conda
only install conda
--node
only install node + nvm
--pnpm
only install pnpm
After installing , restart your terminal (or source ~/.zshrc ) to apply PATH changes, then run check_env.sh to confirm. Command: select-branches Interactively pick a branch for each repo, checkout, and save to .dev-branches . bash scripts/select_branches.sh Non-interactive options:
Use development for all
bash scripts/select_branches.sh --defaults
Specify each branch
bash
scripts/select_branches.sh
\
--hummingbot
development
\
--gateway
core-2.7
\
--api
development
Branch selections are saved to
$WORKSPACE/.dev-branches
and automatically loaded by
install_all.sh
,
build_all.sh
, and
verify_build.sh
.
Command: install-all
Install all three repos in the correct order. Requires
select-branches
first (or pass
--defaults
).
bash
scripts/install_all.sh
What it does (in order):
Removes
solders
from
environment.yml
(pip-only)
make install
in hummingbot →
conda env hummingbot
pip install solders>=0.19.0
into hummingbot env
pnpm install && pnpm build && pnpm run setup:with-defaults
for gateway
conda env create
for hummingbot-api
pip install -e
skip hummingbot conda install
--skip-gateway
skip gateway pnpm install
--skip-api
skip hummingbot-api install
--no-local-hbot
use PyPI hummingbot in API env instead of local source
Command: build-all Build hummingbot wheel and all Docker images in the correct order. bash scripts/build_all.sh Build order: hummingbot wheel ( dist/*.whl ) via python setup.py bdist_wheel hummingbot/hummingbot:dev Docker image hummingbot/gateway:dev Docker image (also rebuilds dist/) hummingbot/hummingbot-api:dev Docker image Each image is also tagged with the branch name (e.g., hummingbot/gateway:core-2.7 ). Options: --wheel-only
only build hummingbot wheel, no Docker
--no-docker
skip all Docker builds
--no-hbot
skip hummingbot builds
--no-gateway
skip gateway builds
--no-api
skip hummingbot-api builds
--tag < name
Docker tag (default: dev)
Command: verify-build Verify that all builds are correct and in sync. bash scripts/verify_build.sh Checks: Each repo is on the expected branch (from .dev-branches ) Hummingbot wheel exists in dist/ Gateway dist/ is built and not stale vs source Local hummingbot source is active in hummingbot-api env Docker images exist with correct branch labels Running services (API + Gateway) are reachable API → Gateway connectivity bash scripts/verify_build.sh --no-docker
skip Docker checks
bash scripts/verify_build.sh --no-running
skip service checks
bash scripts/verify_build.sh --json
JSON output
Command: run-dev-stack Start the full dev stack from source. bash scripts/run_dev_stack.sh Start order: Docker infra (postgres + EMQX) via docker compose up emqx postgres -d Gateway from source in background ( node dist/index.js --passphrase=hummingbot --dev ) Hummingbot API from source in foreground ( uvicorn main:app --reload ) Options: --no-gateway
skip gateway start
--passphrase < pass
gateway passphrase (default: hummingbot)
--stop
stop everything
--status
show running status
Logs: Gateway logs: tail -f ~/.openclaw/workspace/.gateway.log API logs: printed to terminal (foreground) Command: start Check the full dev environment and show a status summary. Step 1: Run environment check bash scripts/check_env.sh --json Step 2: Check repo branches bash scripts/check_repos.sh --json Step 3: Check running services bash scripts/check_api.sh --json bash scripts/check_gateway.sh --json Step 4: Show status checklist Present a checklist like: Dev Environment Status ====================== [x] Prerequisites — conda, node, pnpm, docker, git OK [x] Hummingbot repo — branch: development, env: hummingbot (installed) [x] Gateway repo — branch: development, built: yes [x] Hummingbot API — running at http://localhost:8000 [x] Gateway — running at http://localhost:15888 [ ] Local hummingbot — hummingbot-api NOT using local source Next: run /hummingbot-developer setup-api-dev to wire API to local source Adapt to actual state. If all good, show the test command. Command: setup-hummingbot Install Hummingbot from source on the development branch. Step 1: Check prereqs bash scripts/check_env.sh Step 2: Checkout development branch cd < HUMMINGBOT_DIR
git fetch origin git checkout development git pull origin development Step 3: Remove solders from environment.yml (pip-only package) sed -i '' '/solders/d' setup/environment.yml 2
/dev/null || sed -i '/solders/d' setup/environment.yml Step 4: Install conda environment make install This creates the hummingbot conda env. Takes 3-10 minutes on first run. Step 5: Install solders via pip (not on conda) conda run -n hummingbot pip install "solders>=0.19.0" Interpreting output Output Meaning Next step conda develop . succeeds Dev install registered Proceed PackagesNotFoundError: solders Forgot step 3 Run sed + reinstall Error: Conda is not found conda not in PATH source ~/.zshrc or install Anaconda build_ext errors Missing build tools Install Xcode CLT: xcode-select --install After setup [x] conda env "hummingbot" created [x] solders installed via pip Run hummingbot: /hummingbot-developer run-hummingbot Build image: /hummingbot-developer build-hummingbot Command: run-hummingbot Run the Hummingbot CLI from source. cd < HUMMINGBOT_DIR
conda activate hummingbot ./bin/hummingbot_quickstart.py Or via make: cd < HUMMINGBOT_DIR
make run Note: This opens the interactive Hummingbot CLI. Use exit to quit. To run with a specific config: make run ARGS = "--config-file-name conf_pure_mm_1.yml" Command: build-hummingbot Build a Hummingbot wheel and/or Docker image from source. Build wheel (for local pip installs) cd < HUMMINGBOT_DIR
conda activate hummingbot pip install build wheel
if not already installed
python -m build --wheel --no-isolation Wheel is output to dist/hummingbot-.whl . Important: The wheel must be built with Python 3.12 to match hummingbot-api's environment. Use this wheel to install into other envs: pip install dist/hummingbot-.whl --force-reinstall --no-deps Build Linux wheel for Docker When building hummingbot-api Docker images, you need a Linux wheel (not macOS/Windows). Build inside Docker to ensure compatibility: cd < HUMMINGBOT_DIR
Build Linux wheel using Docker (Python 3.12 to match hummingbot-api)
docker run --rm -v $( pwd ) :/hummingbot -w /hummingbot continuumio/miniconda3 bash -c " apt-get update -qq && apt-get install -y -qq gcc g++ build-essential > /dev/null 2>&1 && conda create -n build python=3.12 cython numpy -y -q && conda run -n build pip install -q build wheel && conda run -n build python -m build --wheel "
Verify the Linux wheel was created
ls dist/linux.whl
Example: hummingbot-20260126-cp312-cp312-linux_aarch64.whl
Platform wheel suffixes: linux_x86_64 — Linux AMD/Intel 64-bit linux_aarch64 — Linux ARM64 (Apple Silicon Docker, AWS Graviton) macosx_11_0_arm64 — macOS Apple Silicon (native only, NOT for Docker) macosx_10_9_x86_64 — macOS Intel (native only, NOT for Docker) Build Docker image cd < HUMMINGBOT_DIR
docker build -t hummingbot/hummingbot:dev -f Dockerfile . Or with make (also cleans first): make build TAG = :dev Tag for use with hummingbot-api: docker build -t hummingbot/hummingbot:development -f Dockerfile . Interpreting output Output Meaning Successfully built + wheel path Wheel ready in dist/ Successfully tagged hummingbot/hummingbot:dev Docker image ready build_ext error Cython compile issue — check conda env is active OOM during Docker build Add --memory 4g flag Command: setup-gateway Install and configure Gateway from source. Step 1: Check prereqs Requires Node.js 20+, pnpm, and git. bash scripts/check_env.sh Step 2: Checkout development branch cd < GATEWAY_DIR
git fetch origin git checkout development git pull origin development Step 3: Install dependencies cd < GATEWAY_DIR
pnpm install If you see USB HID errors on macOS: pnpm install --force Step 4: Build TypeScript pnpm build Step 5: Run setup
Non-interactive with defaults (recommended for dev)
pnpm run setup:with-defaults
Interactive (choose which configs to update)
pnpm run setup Setup creates: conf/ — chain, connector, token, and RPC configs certs/ — TLS certificates (self-signed for dev) Interpreting output Output Meaning Next step Gateway setup complete Ready to start run-gateway tsc errors TypeScript compile error Check Node version ( node --version ≥ 20) pnpm: command not found pnpm not installed npm install -g pnpm ENOSPC Disk space Free up space Command: run-gateway Run Gateway from source in dev mode (HTTP, no TLS). cd < GATEWAY_DIR
pnpm start --passphrase = < PASSPHRASE
--dev Default passphrase matches hummingbot-api setup: hummingbot pnpm start --passphrase = hummingbot --dev What --dev does: Runs in HTTP mode (no TLS) on port 15888 Enables verbose logging Hummingbot API auto-connects at http://localhost:15888 Verify it's running: curl http://localhost:15888/ Watch logs for startup sequence: Gateway listening on port 15888 Solana mainnet-beta initialized ... Configure custom RPC (recommended to avoid rate limits):
After gateway is running, update RPC via API
curl -X POST http://localhost:15888/network/config \ -H "Content-Type: application/json" \ -d '{"chain": "solana", "network": "mainnet-beta", "nodeURL": "https://your-rpc.com"}' Command: build-gateway Build a Gateway Docker image from source. cd < GATEWAY_DIR
docker build \ --build-arg BRANCH = $( git rev-parse --abbrev-ref HEAD ) \ --build-arg COMMIT = $( git rev-parse HEAD ) \ --build-arg BUILD_DATE = $( date -u +%Y-%m-%dT%H:%M:%SZ ) \ -t hummingbot/gateway:dev \ -f Dockerfile . Tag as development for use with hummingbot-api: docker tag hummingbot/gateway:dev hummingbot/gateway:development Verify image: docker run --rm hummingbot/gateway:dev node -e "console.log('OK')" Command: setup-api-dev Configure Hummingbot API to use a local Hummingbot source build instead of the PyPI package. This lets you make changes to Hummingbot and immediately test them via the API without rebuilding Docker images. Step 1: Install hummingbot-api conda environment cd < HUMMINGBOT_API_DIR
make install This creates the hummingbot-api conda env with the PyPI version of hummingbot. Step 2: Install local Hummingbot into hummingbot-api env Option A — Editable install (recommended for active development): conda run -n hummingbot-api pip install -e < HUMMINGBOT_DIR
--no-deps Changes to hummingbot source are reflected immediately (no reinstall needed). Option B — Wheel install (for testing a specific build):
First build the wheel
cd < HUMMINGBOT_DIR
&& conda run -n hummingbot python setup.py bdist_wheel
Install into hummingbot-api env
conda run -n hummingbot-api pip install < HUMMINGBOT_DIR
/dist/hummingbot-*.whl --force-reinstall --no-deps Step 3: Verify local version is active conda run -n hummingbot-api python -c "import hummingbot; print(hummingbot.file)" Should print a path inside
, not site-packages . Step 4: Install solders conda run -n hummingbot-api pip install "solders>=0.19.0" Interpreting output Output Meaning Path inside your hummingbot dir ✅ Local source active Path inside anaconda3/.../site-packages ❌ Still using PyPI version ImportError: No module named hummingbot pip install failed — retry Command: run-api-dev Run Hummingbot API from source with hot-reload, using local Hummingbot. Step 1: Start infrastructure (postgres + EMQX via Docker) cd < HUMMINGBOT_API_DIR docker compose up emqx postgres -d Verify they're healthy: docker compose ps Step 2: Run the API with uvicorn hot-reload cd < HUMMINGBOT_API_DIR
conda run --no-capture-output -n hummingbot-api uvicorn main:app --reload Or via make: make run API is available at http://localhost:8000 Swagger UI at http://localhost:8000/docs What hot-reload means: Changes to *.py files in hummingbot-api are applied immediately. Changes to hummingbot source (editable install) are also picked up on reload. Step 3: Confirm local hummingbot is in use curl -s http://localhost:8000/health | python3 -m json.tool Check API logs for hummingbot version on startup. Useful dev commands
Watch logs
conda run -n hummingbot-api uvicorn main:app --reload --log-level debug
Run on different port
conda run -n hummingbot-api uvicorn main:app --reload --port 8001
Check what's running
docker compose ps curl http://localhost:8000/health Command: test-integration Smoke test the full dev stack — API, Gateway, and Hummingbot connectivity. bash scripts/check_api.sh bash scripts/check_gateway.sh python scripts/test_integration.py What gets tested Test Checks API health GET /health returns 200 API version Confirms hummingbot source path (not PyPI) Gateway health GET / on port 15888 returns 200 API→Gateway API can reach Gateway ( /gateway/status ) Connectors At least one connector visible via API Wallets Gateway wallet list accessible Interpreting results Output Meaning Fix ✓ API running API up — ✓ Gateway running Gateway up — ✓ API→Gateway connected Full stack wired — ✗ API not running Start with run-api-dev — ✗ Gateway not running Start with run-gateway — ✗ API→Gateway: connection refused Gateway URL mismatch Check .env GATEWAY_URL=http://localhost:15888 ✗ Local hummingbot not active Using PyPI version Run setup-api-dev Docker-Based API Development For testing with Docker containers (instead of source), build a custom hummingbot-api image with your hummingbot wheel. Step 1: Build Linux wheel for Docker cd < HUMMINGBOT_DIR
Build Linux wheel using Docker (Python 3.12)
docker run --rm -v $( pwd ) :/hummingbot -w /hummingbot continuumio/miniconda3 bash -c " apt-get update -qq && apt-get install -y -qq gcc g++ build-essential > /dev/null 2>&1 && conda create -n build python=3.12 cython numpy -y -q && conda run -n build pip install -q build wheel && conda run -n build python -m build --wheel " ls dist/linux.whl Step 2: Build hummingbot-api Docker image cd < HUMMINGBOT_API_DIR
Copy wheel to API directory
cp < HUMMINGBOT_DIR
/dist/hummingbot--cp312--linux_*.whl .
Update environment.docker.yml with wheel filename
Then build using Dockerfile.dev
docker build -f Dockerfile.dev -t hummingbot/hummingbot-api:dev . Step 3: Deploy with docker-compose.dev.yml cd < HUMMINGBOT_API_DIR
docker compose -f docker-compose.dev.yml up -d Step 4: Verify development features
Check lp_executor is available (only in development hummingbot)
curl -s -u admin:admin http://localhost:8000/executors/types/available | grep lp_executor Deploying Bots with Custom Images When deploying bots via the API, specify which hummingbot Docker image to use. Deploy with development image curl -X POST http://localhost:8000/bot-orchestration/deploy-v2-controllers \ -u admin:admin \ -H "Content-Type: application/json" \ -d '{ "instance_name": "my-bot", "credentials_profile": "master_account", "controllers_config": ["my_controller.yml"], "image": "hummingbot/hummingbot:development" }' Available hummingbot images Image Description hummingbot/hummingbot:latest Stable PyPI release (default) hummingbot/hummingbot:development Development branch from Docker Hub hummingbot/hummingbot:dev Locally built image DEX connectors require Gateway For connectors like meteora/clmm , Gateway must be running: docker run -d --name gateway -p 15888 :15888 \ -e GATEWAY_PASSPHRASE = admin \ hummingbot/gateway:development Quick Reference Full Dev Setup (first time)
1. Setup repos
cd ~/Documents/hummingbot && git checkout development && git pull cd ~/.openclaw/workspace/hummingbot-gateway && git checkout development && git pull
2. Install hummingbot
cd ~/Documents/hummingbot sed -i '' '/solders/d' setup/environment.yml make install conda run -n hummingbot pip install "solders>=0.19.0"
3. Install gateway
cd ~/.openclaw/workspace/hummingbot-gateway pnpm install && pnpm build && pnpm run setup:with-defaults
4. Wire hummingbot-api to local source
cd ~/.openclaw/workspace/hummingbot-api make install conda run -n hummingbot-api pip install -e ~/Documents/hummingbot --no-deps conda run -n hummingbot-api pip install "solders>=0.19.0"
5. Start everything
cd ~/.openclaw/workspace/hummingbot-gateway pnpm start --passphrase = hummingbot --dev & cd ~/.openclaw/workspace/hummingbot-api docker compose up emqx postgres -d make run Testing a Hummingbot Change
1. Make changes in hummingbot source
2. If editable install: just save the file (hot-reload picks it up)
3. If wheel install: rebuild and reinstall
cd ~/Documents/hummingbot conda run -n hummingbot python setup.py bdist_wheel conda run -n hummingbot-api pip install dist/hummingbot-*.whl --force-reinstall --no-deps
4. Restart API
5. Run tests
python scripts/test_integration.py Repo Paths (defaults) Component Default path Hummingbot ~/Documents/hummingbot Gateway ~/.openclaw/workspace/hummingbot-gateway Hummingbot API ~/.openclaw/workspace/hummingbot-api Override by setting env vars: export HUMMINGBOT_DIR =~ /code/hummingbot export GATEWAY_DIR =~ /code/gateway export HUMMINGBOT_API_DIR =~ /code/hummingbot-api Scripts Reference Script Purpose check_env.sh Verify prereqs (conda, node, pnpm, docker, git) check_repos.sh Show branch + build status for each repo check_api.sh Check if Hummingbot API is running check_gateway.sh Check if Gateway is running test_integration.py End-to-end smoke tests