Installation

Step-by-step guide to install and run the Trade Beam local bot using Docker on macOS, Windows, and Linux.

Prerequisites

Before you begin, make sure you have the following installed on your machine:

Docker Desktop

Download from docker.com - available for macOS, Windows, and Linux. Make sure Docker is running before proceeding.

Deribit API Keys

Create API credentials at deribit.com (or test.deribit.com for testnet). You need both the API Key and API Secret.

docker-compose.yml

Downloaded from the FM Portal with your subscription UUID pre-filled.

1Prepare Your Directory

Create a folder for the bot and move the downloaded docker-compose.yml into it:

mkdir ~/trade-beam-bot && cd ~/trade-beam-bot
# Move your downloaded docker-compose.yml here

2Configure Your Environment

Create a .env file in the same directory with your Deribit API credentials:

# .env
DERIBIT_API_KEY=your_api_key_here
DERIBIT_API_SECRET=your_api_secret_here

# The UUID is already set in docker-compose.yml,
# but you can override it here if needed:
# SUBSCRIPTION_UUID=your-uuid-from-portal

Security Notice: Never share your .env file or commit it to version control. Your Deribit API keys grant access to your trading account.

See the full Configuration Reference for all available environment variables.

3Start the Bot

Make sure Docker Desktop is running, then start the bot with:

docker compose up -d

This pulls the bot image, starts a Redis container for local caching, and launches the trading bot in the background. First run may take a minute to download the images.

4Verify the Bot is Running

Check that the bot started successfully:

# Check container status
docker compose ps

# Health check
curl http://localhost:8080/healthz

# View logs
docker compose logs -f bot

You should see a 200 OK response from the health check. The logs will show the bot connecting to Deribit and placing initial grid orders.

Platform Notes

macOS

Docker Desktop for Mac runs Linux containers in a lightweight VM. No additional configuration is needed. If you get permission errors, make sure Docker Desktop is fully started (whale icon in the menu bar is stable, not animating).

Windows

Requires WSL 2 (Windows Subsystem for Linux). Docker Desktop installs this automatically. Use PowerShell or Windows Terminal to run the commands above. If you encounter network issues, ensure your firewall allows Docker connections.

Linux

You can use Docker Engine instead of Docker Desktop. Install via your package manager (apt, dnf, etc.). Make sure your user is in the docker group to avoid using sudo: sudo usermod -aG docker $USER

Troubleshooting

Container keeps restarting

Check the logs with docker compose logs bot. Common causes: invalid API keys, missing environment variables, or network connectivity issues to Deribit.

Port 8080 already in use

Another service is using port 8080. Either stop that service or change the port mapping in docker-compose.yml from 8080:8080 to 9090:8080.

Health check fails

Wait 10-15 seconds after starting for the bot to initialize. Verify the container is running with docker compose ps. If the status shows "unhealthy", check the logs for startup errors.

Cannot connect to Deribit

Ensure your machine has internet access and no firewall is blocking WebSocket connections to wss://www.deribit.com/ws/api/v2. If using testnet, verify your keys are from test.deribit.com, not the live site.

Managing the Bot

# Stop the bot
docker compose down

# Restart the bot
docker compose restart

# Update to the latest version
docker compose pull && docker compose up -d

# View real-time logs
docker compose logs -f bot

Download

Configuration