ImageTools

Get started in minutes

ImageTools is self-hosted. Run it locally for development, or in Docker on your own server; both lead to the same upload screen. Then connect the Android app and browser extensions to it.

Option 1 — Local development (fastest)

Prerequisites: Python 3.11+, Node.js 20+, npm. From the repo root:

git clone https://github.com/githuba42r/ImageTools.git
cd ImageTools
./run-all.sh

That script creates the Python venv, installs backend and frontend dependencies, and starts both. Then open:

  • Web UI: http://localhost:5173
  • Backend: http://localhost:8001 (API docs at /api/v1/docs)

Prefer two terminals? Use ./run-backend.sh in one and ./run-frontend.sh in the other — see QUICKSTART.md for the fully manual path and troubleshooting.

Smoke test

  1. Drag and drop 2–3 images onto the upload area.
  2. Click the Email preset on one image and watch the compression ratio appear.
  3. Click Undo to revert; select several images to bulk-compress; download the results.

Option 2 — Self-hosted with Docker

One container ships the whole app (FastAPI backend + built Vue frontend), persisting uploads and SQLite in a single volume:

cd ImageTools
docker-compose up --build -d
# → http://localhost:8082

Set SESSION_SECRET_KEY, INSTANCE_URL and CORS_ORIGINS for anything beyond localhost, and consider the deployment/ stack (nginx + Basic Auth, or Authelia) for production. Everything is covered on the Docker deployment page.

The Android app

Share images straight from your phone: the Android app acts as a share target, so any photo from the gallery or camera can land in your ImageTools session — one tap on the normal Android share sheet, then it's in your web gallery, ready to shrink and send on.

Download the APK (GitHub Releases) ↗
  1. Grab the latest .apk from GitHub Releases and install it on your device (or build it yourself — see android-app/README.md; release builds land in dist/ via ./build.sh).
  2. Open the ImageTools web interface and generate a QR code.
  3. Scan the QR code in the Android app to pair.
  4. Share images from any app to ImageTools — they appear automatically in the web gallery.

Google Play Store publication is on the roadmap.

After you're up: the rest of the ecosystem

Browser extensions

Capture the visible area, full page or a selection in Chrome & Firefox — copy to clipboard or lodge it with your instance, tagged. Pair via a one-time registration URL.

→ Browser extensions

MCP server

Point Claude Code at /mcp/ with a token minted in Settings → MCP Access Tokens, then just say "use my last 2 screenshots".

→ MCP server

Where to go next

  • User guide — presets, editing, AI chat, export options.
  • docs/ENV_CONFIG.md — full environment configuration reference.
  • README — architecture, security checklist and contributing.