Get GavelOwl running

Never touched Docker before? That's fine - you install one free app, then never think about it again. Docker is what lets GavelOwl run the same way on any computer without you installing a bunch of separate pieces by hand.

• Mac or Windows: download Docker Desktop, open the installer, and click through it like any other app. On Windows it may ask about "WSL 2" - just accept the prompts, it sets that up for you. Open Docker Desktop once after installing.
• Linux: install Docker Engine following the instructions for your distribution.

You'll know it worked when you see a small whale icon in your menu bar (Mac) or system tray (Windows). That's all you need to do here - leave it running in the background and don't worry about clicking into it.

Where should this actually run?

• Your own computer - free, and the simplest place to start. The one catch: your computer needs to stay on and awake for GavelOwl to keep checking eBay. Close the lid or shut it down, and alerts pause until it's back on.
• A small rented server ("VPS") - runs 24/7 even when your own computer is off. Costs roughly $4-6/month from providers like Hetzner or DigitalOcean. Every command in this guide works identically on a rented server - you just type them into an SSH terminal connected to it instead of your own computer. Renting a server is a separate thing to learn on its own, so it's fine to start on your own computer first and move to a server later if you want it running around the clock.

There are two ways to do this - pick whichever you're more comfortable with.

curl -fsSL https://gavelowl.com/install/free | bash

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 (steps 3-5). It's a dotfile, so it won't show up in a plain ls - use ls -a or your editor's file browser to see it.
• README.md - the full command reference, for offline reading.
• the .zip also includes SETUP.md with the exact registry-login and pull commands to run by hand, since it can't run them for you the way the script does.

This is the part people usually dread most. It's mostly clicking "Next" a few times. One thing worth knowing upfront is that the very first sign-up step can take eBay up to a day to approve.

1. Sign up as an eBay developer (one-time, may take a day)

1. If you haven't used the Developer Portal before, it'll ask you to join the developer program with a short form.
2. Sometimes eBay approves this instantly. Sometimes it goes to manual review and you'll get a confirmation email up to a day later - if that happens, just wait for the email before continuing.

2. Create your App ID and Cert ID (instant, once approved)

1. Once you're in, find Application Keys (usually under your account/profile menu).
2. Look for the Production section (not "Sandbox" - that's a practice version, we want the real one) and click Create a keyset. eBay's exact wording shifts occasionally, but it's always this kind of button.
3. You may be asked to accept a developer agreement - that's standard, just accept it.
4. eBay instantly shows two values: App ID (Client ID) and Cert ID (Client Secret). Copy both somewhere safe - you'll paste them into .env in step 5.

This part itself is instant - the only wait, if any, is the developer sign-up above.

3. Get a User Token - if you want messages, sales, offers, or sniping (so basically yes)

Only want new-listing alerts? Skip this whole section and leave EBAY_AUTH_TOKEN blank in your .env file - just don't /enable messages, sales, offers, or sniping later.

This part lets the app read your inbox and sold items, and place bids on your behalf - so eBay makes you explicitly approve it, the same idea as clicking "Sign in with Google" on some other website. You're approving specific permissions, not handing over your password.

1. On the same Application Keys page, find the User Tokens tab.
2. Click Sign in to Production (sometimes labeled "Get a Token from eBay via Your Application").
3. You land on a completely normal eBay login page - sign in like you always do.
4. eBay shows a screen listing what the app is asking permission for. Click I Agree.
5. You're redirected back and shown a very long string starting with something like v^1.1#i^1#.... Copy the whole thing, even though it looks unreasonably long - that's your token.

No account creation, no phone verification - just two chats with two bots.

1. Open Telegram and search for BotFather (it has a blue verified checkmark - that's the official way to create bots). Start a chat and send /newbot.
2. It asks for a display name (anything you like) and a username (must be unique and end in "bot", e.g. myebayalerts_bot).
3. BotFather replies with a token - a long string like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyz. Copy it - that's TELEGRAM_APITOKEN.
4. Now search for @userinfobot and send it any message. It instantly replies with your numeric Telegram ID - copy that number as TELEGRAM_CHAT_ID.

Open the .env file from step 2 in any text editor, and paste in what you collected:

That's it - search terms, marketplaces, allowed countries, and which features are even on are all configured later by chatting with the bot (step 7), not in this file.

Open a terminal in the gavelowl/ folder from step 2 (on Mac: Finder → right-click the folder → "New Terminal at Folder"; on Windows: Explorer → type cmd in the address bar and press Enter) and run:

docker compose up -d --build

On 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.

Everything here takes effect on the next poll cycle - no restart needed.

Sniping is temporarily unavailable - eBay requires an application to be specifically authorized to place bids via its API, and this one doesn't have that authorization yet. /snipe will tell you this directly if you try it. Everything else in this guide (listing search, messages, sales, offers, /watching) is unaffected. The rest of this section describes how sniping works once that's resolved.

/disable sniping only stops new proposals from being accepted - it doesn't cancel bids you've already confirmed. Use/cancel for those.

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