Repolode
Submit
dsgnr

dsgnr/portchecker.io

Open-source TCP port checker with a REST API and web UI, self-hostable via Docker and built on Litestar.

View on GitHubWebsite
Stars
198
Forks
10
Open issues
1
Last commit
6 days ago

What is it?

portchecker.io checks whether a TCP port is reachable on a given hostname or IP address. It is useful for troubleshooting network setups, verifying firewall rules, and seeing which ports are exposed to the outside.

The project has two parts: a static React front end served by Nginx, and a Python API built with Litestar and run under gunicorn with uvicorn workers. Both can be run standalone for development or brought up together with Docker Compose, using prebuilt images published to GitHub Container Registry.

By default the API refuses to check private IP addresses from the IANA special-purpose ranges; setting the ALLOW_PRIVATE option enables them. The API also exposes a Prometheus /metrics endpoint for response times and status codes, and includes smoke and Playwright browser tests in CI.

Key features

  • 01Checks TCP port availability for any hostname or IP address.
  • 02Exposes a REST API with documented routes at /docs.
  • 03Includes a web UI served by Nginx.
  • 04Runs in Docker, with prebuilt images and Docker Compose files.
  • 05Provides a Prometheus metrics endpoint for API monitoring.
  • 06Can optionally allow checks against private IP ranges.

Use cases

  • Checking whether a service's port is open after changing firewall rules.
  • Verifying from outside a network that a server's ports are exposed as intended.
  • Integrating port checks into scripts or monitoring via the REST API.
  • Self-hosting a port checker on your own infrastructure.

Quick start

  1. 1

    Start the production stack with Docker Compose (front-end on port 8080, API on port 8000)

    docker-compose up

Things to know

  • Licensed under GPL-3.0, a copyleft license that requires derivative works to be open-sourced under the same terms.
  • Standalone development needs Python 3.13 with Poetry and Node 26 or newer, so Docker is the simpler route.

In collections

Self-hosted apps

Topics

#port-scanner#tcp#networking#self-hosted#docker#rest-api#firewall#api#devops#docker-compose

FAQ

What is portchecker.io?
Open-source TCP port checker with a REST API and web UI, self-hostable via Docker and built on Litestar. portchecker.io checks whether a TCP port is reachable on a given hostname or IP address. It is useful for troubleshooting network setups, verifying firewall rules, and seeing which ports are exposed to the outside.
Is portchecker.io free to use? What license does it have?
portchecker.io is open source under the GPL-3.0 license. Check the license terms before using it in commercial products.
Is portchecker.io still maintained?
Actively maintained. The last commit to portchecker.io was on Nov 1, 2026.
What can I use portchecker.io for?
Checking whether a service's port is open after changing firewall rules. Verifying from outside a network that a server's ports are exposed as intended. Integrating port checks into scripts or monitoring via the REST API. Self-hosting a port checker on your own infrastructure.
How do I install portchecker.io?
Start the production stack with Docker Compose (front-end on port 8080, API on port 8000): docker-compose up
Where can I get portchecker.io?
The source code and installation instructions are on GitHub: https://github.com/dsgnr/portchecker.io

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects