Developer skill for running Hummingbot and Gateway from source, building wheel and Docker images, and testing against Hummingbot API running from source. Use this skill when a developer wants to build, run, or test Hummingbot components locally.
Developer skill for running Hummingbot and Gateway from source, building wheel and Docker images, and testing against Hummingbot API running from source. Use this skill when a developer wants to build, run, or test Hummingbot components locally.
metadata
{"author":"hummingbot"}
commands
{"start":{"description":"Check dev environment — repo branches, prereqs, running services"},"install-deps":{"description":"Auto-install missing dev dependencies (conda, node, pnpm, docker, git)"},"select-branches":{"description":"Interactively pick branches for hummingbot, gateway, and hummingbot-api"},"install-all":{"description":"Install all three repos in order (hummingbot → gateway → hummingbot-api)"},"build-all":{"description":"Build hummingbot wheel + all Docker images in order"},"verify-build":{"description":"Verify all builds are correct and in sync across repos"},"run-dev-stack":{"description":"Start the full dev stack from source (infra + gateway + API)"},"setup-hummingbot":{"description":"Install Hummingbot from source (branch, conda env, solders fix)"},"run-hummingbot":{"description":"Run Hummingbot CLI from source"},"build-hummingbot":{"description":"Build Hummingbot wheel and Docker image from source"},"setup-gateway":{"description":"Install and configure Gateway from source (pnpm install/build/setup)"},"run-gateway":{"description":"Run Gateway from source in dev mode"},"build-gateway":{"description":"Build Gateway Docker image from source"},"setup-api-dev":{"description":"Configure Hummingbot API to use local Hummingbot source (pip install -e)"},"run-api-dev":{"description":"Run Hummingbot API from source with hot-reload against local Hummingbot"},"test-integration":{"description":"Smoke test the full stack — API, Gateway, and Hummingbot connectivity"}}
hummingbot-developer
Developer workflow skill for building and running the full Hummingbot stack from source.
Commands (run as /hummingbot-developer <command>):
Override with env vars: HUMMINGBOT_DIR, GATEWAY_DIR, HUMMINGBOT_API_DIR, or WORKSPACE.
Command: install-deps
Auto-install all missing dev dependencies. Safe to re-run — skips anything already installed.
bash scripts/install_deps.sh
Installs (only if missing):
Homebrew (macOS)
Xcode Command Line Tools (macOS — needed for Cython build_ext)
Miniconda (conda)
Node.js v22 (via nvm, Homebrew, or installs nvm)
pnpm (via npm or Homebrew)
Git
Docker Desktop (macOS — via Homebrew cask or opens download page)
Options:
--check # 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 <hummingbot_dir> --no-deps → wires local source into API env
Options:
--skip-hbot # 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
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.
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"}'
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 wheelcd <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 <HUMMINGBOT_DIR>, 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.
cd <HUMMINGBOT_API_DIR>
# Copy wheel to API directorycp <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.
# 1. Setup reposcd ~/Documents/hummingbot && git checkout development && git pull
cd ~/.openclaw/workspace/hummingbot-gateway && git checkout development && git pull
# 2. Install hummingbotcd ~/Documents/hummingbot
sed -i '''/solders/d' setup/environment.yml
make install
conda run -n hummingbot pip install "solders>=0.19.0"# 3. Install gatewaycd ~/.openclaw/workspace/hummingbot-gateway
pnpm install && pnpm build && pnpm run setup:with-defaults
# 4. Wire hummingbot-api to local sourcecd ~/.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 everythingcd ~/.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 reinstallcd ~/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
