Setup guide
Get GavelOwl running
Ten minutes, start to finish. You'll need a machine that can run Docker (your own computer or a small server), an eBay developer account, and a Telegram bot token.
Get your license and the app files
There are two ways to do this - pick whichever you're more comfortable with.
Option A - run in Terminal
curl -fsSL https://gavelowl.com/install/free | bashOption B - download the files
Download the .zipIncludes docker-compose.yaml, .env, README.md, and SETUP.md with the commands to run manually.
Either way, run it wherever you want GavelOwl to live - it creates a gavelowl/ folder there containing:
docker-compose.yaml- ready to run, no editing needed..env- a template for your credentials (step 2). It's a dotfile, so it won't show up in a plainls- usels -aor your editor's file browser to see it.README.md- the full command reference, for offline reading.- the
.zipalso includesSETUP.mdwith the exact registry-login and pull commands to run by hand, since it can't run them for you the way the script does.
"Installation walkthrough" video coming soon
Fill in your .env file
This is the only configuration file you'll ever need to edit by hand. Open .env and fill in:
| Variable | Needed for | Where to get it |
|---|---|---|
| EBAY_CLIENT_ID | Any feature | eBay Developer Portal → your app's App ID (production keyset) |
| EBAY_CLIENT_SECRET | Listing search | Same app's Cert ID |
| EBAY_AUTH_TOKEN | Messages, sales, offers, sniping | Developer Portal → User Tokens → "Sign in to Production" (Auth'n'Auth) |
| TELEGRAM_APITOKEN | Always | Message @BotFather on Telegram → /newbot |
| TELEGRAM_CHAT_ID | Always | Message your new bot once, then check https://api.telegram.org/bot<token>/getUpdates |
That's it - search terms, marketplaces, allowed countries, and which features are even on are all configured later by chatting with the bot (step 4), not in this file.
Start it up
docker compose up -d --buildOn its very first run, GavelOwl has no history to compare against yet - it quietly records everything it currently finds instead of alerting on all of it at once, then starts alerting from the next poll. Message your bot with /help to confirm it's alive.
Configure by chatting with the bot
Everything here takes effect on the next poll cycle - no restart needed.
/settingsShow current search terms, marketplaces, allowed countries, and enabled features.
/setterms <term1,term2,...>Set the listing search terms.
/setmarketplaces <EBAY_DE,EBAY_GB,...>Set which eBay site(s) to search.
/setcountries <DE,FR,...|all>Restrict to seller countries, or allow all.
/enable <listing|messages|sales|offers|sniping>Turn a feature on.
/disable <listing|messages|sales|offers|sniping>Turn a feature off.
"Configuring alerts via Telegram" video coming soon
Sniping an auction (optional)
A bid placed this way is a real, binding commitment to buy if it wins - there's no undo once it fires. Read this whole section before your first snipe.
/snipe <link or item ID> <bid>Validates the listing and stages a bid - does not schedule it yet.
/confirm [item ID]Actually schedules the most recently staged bid to fire a few seconds before the auction ends. Must be sent within a couple of minutes of /snipe, or it expires.
/snipesLists scheduled snipes with the auction's live price and bid count.
/change <item ID> <new bid>Update a scheduled snipe's bid amount.
/cancel <item ID>Cancel a scheduled snipe.
/disable sniping only stops new proposals from being accepted - it doesn't cancel bids you've already confirmed. Use/cancel for those.
"Sniping your first auction" video coming soon
If something breaks
If the same category (listing search, messages, sales, or offers) fails for a few polls in a row, you'll get an actual Telegram alert about it - almost always an expired or broken token. Otherwise, check the logs:
docker compose logs