# vinted-bot

> Free, open-source app that watches Vinted searches and sends a message (Telegram, Discord, email and other apps, RSS or a webhook) when a new listing matches. It runs on the user's own computer or server, never logs in to Vinted, and has a web dashboard at http://localhost:8000 where all setup happens. Not affiliated with Vinted. MIT licensed. Source: https://github.com/jasp-nerd/vinted-bot

This file is a complete guide for an AI assistant helping someone install and use vinted-bot. The person is often not technical. Use only the commands in this file; do not invent commands, flags or settings. If something here doesn't match what the person sees, say so and point them to the issue tracker rather than guessing.

## How to help

- First ask what computer they have (Windows, Mac, Linux, Raspberry Pi, or a NAS such as Unraid, Synology, Umbrel or CasaOS) and whether it stays switched on.
- Give one small step at a time. Say exactly where to click or what to paste and what they should see next. Wait for them to confirm before the next step.
- Never ask them to paste a Discord webhook link, Telegram bot token, dashboard password or any other secret into the chat. Tell them where in the app to paste it instead.
- When something fails, ask for the exact error text, then use the Troubleshooting section below.

## Facts that matter

- Alerts only arrive while the computer running vinted-bot is on, awake and online. A laptop that sleeps sends nothing while asleep. Always-on options: a Raspberry Pi, a NAS, a mini PC, an old laptop left plugged in, or a small rented server (a few euros a month).
- No Vinted account is involved. It never asks for Vinted login details. Anything asking for Vinted credentials is not this app.
- No configuration file is needed, ever. Searches, alert destinations, the Telegram bot token, the dashboard password and phone access are all set in the dashboard. Never tell the person to create or edit a .env file for these.
- The dashboard is at http://localhost:8000 on the computer it runs on. It has no password until one is set in Settings, Password. That is fine on the person's own computer. To open it on a phone: Settings, "Open on your phone", switch on "Allow my phone and other devices"; it asks for a password (it suggests one), then shows a QR code and the address to type. It only reaches devices on the same Wi-Fi or home network, not the internet. (Servers and Docker can instead fix VINTED_BOT_WEB_AUTH_TOKEN and VINTED_BOT_WEB_HOST in the environment; those win over the dashboard.)
- Forgot the dashboard password: run `vinted-bot reset-password` on the computer running it (Docker: `docker compose exec vinted-bot vinted-bot reset-password`). It prints a new one.
- Price limits include Vinted's buyer protection fee, so they match what the person actually pays.
- The first check of a new search is silent on purpose, so there is no flood of old listings. Alerts start with listings that appear after that.
- Vinted adds new uploads to its search a few minutes after they are posted, and every tool that reads the search sees them then; vinted-bot checks every minute after that. Nothing can be instant, and the app does not measure or show this delay.
- Vinted moved its search to a new address in September 2026. Versions before 2.0.0 find nothing since then. If someone installed earlier, update first (see Updating).

## Install

Pick exactly one. The installers need no admin rights and no Docker. They install uv (a helper that downloads Python) and vinted-bot into the user's own folder, ask whether to start at login, start the app, and open the dashboard.

### Windows 10 or 11

1. Open PowerShell: Start menu, type PowerShell, press Enter.
2. Paste this and press Enter:

    powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/install.ps1 | iex"

3. Answer the question about starting at sign-in (Y is recommended).
4. The browser opens http://localhost:8000. The app runs in the background with no window.

Keep the PC awake: Settings, System, Power, set "Make my device sleep" to Never while plugged in.

### macOS

1. Open Terminal: press Cmd+Space, type Terminal, press Enter.
2. Paste this and press Enter:

    curl -LsSf https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/install.sh | sh

3. It asks whether to keep the Mac awake while plugged in, and whether to start at login. Yes to both is recommended for reliable alerts. macOS may then show a "Background Items Added" notice; that is expected.
4. The browser opens http://localhost:8000.

### Linux, or a Raspberry Pi (64-bit Raspberry Pi OS)

    curl -LsSf https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/install.sh | sh

To make it start at boot with nobody logged in (useful on a Pi), the installer may ask them to run:

    sudo loginctl enable-linger $USER

A Pi without a screen: open the dashboard from another computer by running this on that computer, then visiting http://localhost:8000 there (replace pi and raspberrypi.local with their user and Pi name):

    ssh -L 8000:localhost:8000 pi@raspberrypi.local

### Docker (any computer that already has Docker)

    mkdir vinted-bot && cd vinted-bot
    curl -fsSLO https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/docker-compose.yml
    docker compose up -d

Then open http://localhost:8000 on that computer. With Docker, put `docker compose exec vinted-bot` in front of any `vinted-bot` command below. Settings such as the Telegram bot token or a dashboard password go in the `environment:` block of docker-compose.yml (the common ones are there, commented out); after changing it, run `docker compose up -d`.

### NAS

- Unraid: not in Community Applications yet. In the Unraid terminal run
      curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-vinted-bot.xml https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/deploy/unraid/vinted-bot.xml
  then Docker, Add Container, and pick vinted-bot under Template.
- Umbrel: not in an Umbrel app store yet. Use the Docker steps above over SSH (ssh umbrel@umbrel.local).
- CasaOS or ZimaOS: App Store, Custom Install, import https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/deploy/casaos/docker-compose.yml
- Synology (DSM 7.2+): Container Manager, Project, Create, paste the docker-compose.yml from the Docker section.

On a NAS the dashboard is reachable from the whole home network, so set a dashboard password first: in the dashboard, Settings, Password, Set a password.

## First use

1. Open http://localhost:8000. On first start, the dashboard walks through setup, one screen at a time.
2. "Which Vinted do you shop on?": pick their country's site (vinted.fr, vinted.de, vinted.co.uk, vinted.nl, and so on).
3. "What are you looking for?": easiest is to search on the Vinted website as usual, set the filters, copy the address from the browser's address bar and paste it here. Or build the search on this screen. A maximum price (including buyer protection), words to leave out, sizes and condition can be set here or later.
4. "Where should we tell you?": Telegram and Discord come first (see Alerts below); a phone notification app (ntfy), email and the user's own app (a webhook) are under "More options". Nothing is preselected. Skipping is allowed; finds then only show in the dashboard.
5. "Did it arrive?": a test message is sent. Confirm it arrived, or send it again.
6. "You're all set". The first check is silent; new matching listings arrive from then on. More searches: the Searches tab. More places for alerts: the Alerts tab, "Add a place".

## Alerts

### Discord

1. In Discord, the person needs a server where they can manage channels (they can create their own server for free with the + button).
2. Right-click the channel, Edit Channel, Integrations, Webhooks, New Webhook, Copy Webhook URL.
3. In the vinted-bot dashboard, choose Discord (during setup, or Alerts, "Add a place") and paste the link there.
4. Send a test message from the dashboard.

The webhook link works like a password for posting into that channel. It goes only into the dashboard.

### Telegram

1. In Telegram, open @BotFather (blue tick), tap Start, send /newbot, choose any name, then a username ending in "bot". BotFather replies "Done! Congratulations" with a token under "Use this token to access the HTTP API". Tapping the token copies it.
2. In the dashboard: Alerts, Add a place, Telegram (or the Telegram option in first-run setup). Paste the token in "Bot token" and press "Check and save". vinted-bot checks it with Telegram and shows the bot's @name. No restart is needed. A made-up or mistyped token gets a clear error instead.
3. Press "Connect my chat". The "Open Telegram" button opens the bot with a one-time code; press Start. The dashboard notices within seconds and says Connected. For a group, add the bot to the group first and send the code shown inside the group. The code expires after 30 minutes. `vinted-bot pair-telegram --bot-username THEBOTNAME` prints the same link from the command line.

A Telegram bot cannot message someone first; that is a Telegram rule, which is why the link step exists.

### More options: ntfy, email, RSS and webhooks

- Email and other apps (Slack, Pushover, Gotify, Matrix and more) go through Apprise, under the dashboard's other options.
- ntfy: a phone push app with no account. The public ntfy.sh server allows about 250 messages a day per internet address, so it only suits focused searches; for busy ones use Telegram or Discord. Install the ntfy app, pick a hard-to-guess topic name, subscribe to it in the app, and add an ntfy destination with that topic in the dashboard.
- RSS: each search has a feed at http://localhost:8000/rss/SEARCH_ID.xml.
- Webhook: any URL that accepts a JSON POST (n8n, Home Assistant, a script).
- Email: Alerts, Add a place, Email. Type the address, pick the provider (Gmail, Outlook, Yahoo, iCloud) and paste an app password from the provider's security settings (the normal password usually doesn't work). For any other provider pick "Another provider, or my own mail server" and fill in its outgoing (SMTP) server, port and encryption from the provider's help pages.

## Updating

- Installed with the Windows, macOS or Linux installer: click "Update now" in the dashboard's banner (or Settings, Updates), or run the same install command again. Both keep all searches. If the dashboard then asks for a restart (it was not set to start at login), run `vinted-bot run` again.
- Docker: `docker compose pull && docker compose up -d`
- NAS: pull the new image with the NAS's own container update (Unraid: Docker, Check for Updates).

The dashboard says when a new version is out. Check the version with `vinted-bot --version`.

## Stopping and removing

Stop:
- Windows (PowerShell): `Get-Process vinted-bot | Stop-Process`
- macOS, if they said yes to starting at login: `launchctl bootout gui/$(id -u)/io.github.jasp-nerd.vinted-bot` (it starts again at the next login). Otherwise: `pkill -f 'vinted-bot run'`
- Linux, if they said yes to starting at login: `systemctl --user stop vinted-bot` (it starts again at the next login). Otherwise: `pkill -f 'vinted-bot run'`
- Docker: `docker compose down`

Running the install command again starts it again (Docker: `docker compose up -d`).

Remove (searches are kept in the data folder until it is deleted):
- Windows: `powershell -ExecutionPolicy ByPass -c '$env:VINTED_BOT_UNINSTALL=1; irm https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/install.ps1 | iex'`
- macOS and Linux: `curl -LsSf https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/install.sh | sh -s -- --uninstall`
- Docker: `docker compose down -v` (the -v also deletes the searches)

To keep a copy of the searches first: `vinted-bot backup vinted-bot-backup.db` (Docker: `docker compose exec vinted-bot vinted-bot backup /data/backup.db`, then `docker compose cp vinted-bot:/data/backup.db ./vinted-bot-backup.db`). Never copy app.db itself while the app runs.

## Troubleshooting

Go in this order.

1. Old version: run `vinted-bot --version`. Anything below 2.0.0 stopped working in September 2026. Update.
2. Is it running? Open http://localhost:8000. If the page doesn't load, start it again by running the install command again (Docker: `docker compose up -d`) and look at the log (step 6).
3. Search health: the dashboard shows each search's state, or run `vinted-bot status`. States: ok (working, just nothing new matched), stale (Vinted stopped updating that search; it repairs itself, restart if it lasts over an hour), failing (see the error shown).
4. Vinted reachable from this machine: run `vinted-bot check --url "PASTE A VINTED SEARCH URL"`. Listings printed = connection fine. "Blocked" = Vinted refuses this internet connection. Confirm with (use their country's site):
       macOS/Linux:  curl -s -c - -L "https://www.vinted.fr/" | grep access_token_web
       Windows:      curl.exe -s -c - -L "https://www.vinted.fr/" | Select-String access_token_web
   A line printed = fine. Nothing printed = this connection is refused by Vinted (common on cloud servers and some VPNs). Fixes: wait (often temporary), check less often, turn off a VPN, or run it at home.
5. "ok" but nothing arrives: the price limit includes buyer protection; excluded words may catch more than intended; the search may simply have nothing new (compare on the Vinted website). Promoted (bumped) listings are skipped on purpose.
6. Logs: Windows %LOCALAPPDATA%\vinted-bot\vinted-bot.log; macOS ~/Library/Application Support/vinted-bot/vinted-bot.log; Linux `journalctl --user -u vinted-bot`; Docker `docker compose logs --tail 200 vinted-bot`.
7. Alerts stopped but searches are fine: the destination may have been switched off because Discord or Telegram said it no longer exists (deleted webhook, blocked bot). Remove it and add it again in the dashboard.
8. "Port 8000 is taken" during install: another program (often an older Docker copy) uses it. Stop that, or install with VINTED_BOT_WEB_PORT=8001 (macOS/Linux: put it before `sh` in the install command; Windows: run `$env:VINTED_BOT_WEB_PORT = 8001` first) and use http://localhost:8001.
9. "command not found" right after installing: open a new terminal window.
10. Windows "running scripts is disabled": use the install command exactly as given, including -ExecutionPolicy ByPass.
11. Docker "unable to open database file": set PUID and PGID in docker-compose.yml to the owner of the data folder (`id` prints it).

Still stuck: open an issue at https://github.com/jasp-nerd/vinted-bot/issues/new/choose with the output of `vinted-bot status` and the last part of the log. Check the log has no tokens or webhook links before posting.

## More detail

- [README](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/README.md)
- [Self-hosting: Pi, NAS, VPS, backups, updating](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/docs/self-hosting.md)
- [Troubleshooting](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/docs/troubleshooting.md)
- [Configuration: every setting](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/docs/configuration.md)
- [NAS and cloud templates](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/deploy/README.md)
- [Legal notes](https://raw.githubusercontent.com/jasp-nerd/vinted-bot/main/docs/legal.md)
