SwitchFetcher

SwitchFetcher is a lightweight remote hosts provider for SwitchHosts. It resolves custom domain lists through DNSChecker, caches results in Redis, and serves SwitchHosts-compatible IPv4 or IPv6 hosts text.

Features

• Generate remote hosts subscriptions for SwitchHosts.
• Resolve A and AAAA records for custom domains.
• Choose DNSChecker country nodes, with jp as the default.
• Optionally probe TCP connectivity and return the fastest IP.
• Cache DNS results in Redis to reduce repeated lookups.
• Protect endpoints with an API token or signed subscription URL.

Quick Start

Copy the example environment file and update the secrets first:

cp .env.example .env

Start the service with Docker Compose:

docker compose up -d --build

Check that the API is healthy:

curl "http://localhost:8000/health"

Expected response:

{"status":"ok"}

Configuration

Variable	Default	Description
API_TOKEN	change-me-switchfetcher-token	Access token for protected endpoints.
SIGNING_SECRET	change-me-signing-secret	Secret used to create signed subscription URLs.
REDIS_URL	redis://redis:6379/0	Redis connection string.
CACHE_TTL_SECONDS	3600	DNS result cache TTL.
COUNTRY_CODE	jp	Default DNSChecker country code.
DNSCHECKER_NODE_IDS	jp:208,220;*:220	DNSChecker node IDs to try per country. Use country:id,id;*:id format.
DNSCHECKER_TRUST_ENV	false	Whether DNSChecker requests should use proxy settings from environment variables.
FASTEST_DEFAULT	true	Whether to return only the fastest probed IP by default.
TCP_PROBE_PORT	80	TCP port used for fastest-IP probing.
TCP_PROBE_TIMEOUT_SECONDS	2	TCP probe timeout in seconds.
REQUEST_TIMEOUT_SECONDS	30	Upstream request timeout in seconds.

SwitchHosts Subscription

Add a remote subscription in SwitchHosts with a URL like this:

http://YOUR_SERVER:8000/hosts/ipv4?domains=tmdb.org,api.tmdb.org,www.imdb.com&country=jp&token=YOUR_API_TOKEN

IPv6 subscription:

http://YOUR_SERVER:8000/hosts/ipv6?domains=tmdb.org,api.tmdb.org,www.imdb.com&country=jp&token=YOUR_API_TOKEN

Query parameters:

Parameter	Required	Description
domains	Yes	Domains separated by commas, semicolons, or new lines.
country	No	DNSChecker country code. Defaults to COUNTRY_CODE.
fastest	No	When true, probe resolved IPs and return the fastest one.
token	No	API token. You can also use Authorization: Bearer <token>.

JSON API

Resolve domains and receive structured JSON:

curl "http://localhost:8000/resolve?domains=tmdb.org,www.imdb.com&record_type=A&country=jp&token=YOUR_API_TOKEN"

record_type accepts A or AAAA.

Signed URLs

If you do not want to keep the main API token in a long-lived SwitchHosts subscription, configure SIGNING_SECRET and generate a signed query:

curl "http://localhost:8000/tools/sign?path=/hosts/ipv4&domains=tmdb.org,api.tmdb.org&country=jp&fastest=true&expires=4102444800&token=YOUR_API_TOKEN"

The response contains path and signed_query. Use them together:

http://YOUR_SERVER:8000/hosts/ipv4?SIGNED_QUERY_FROM_RESPONSE

Development

Create and activate a virtual environment:

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS or Linux:

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Copy the example environment file:

cp .env.example .env

For local development outside Docker, update .env so Redis points to your local machine:

REDIS_URL=redis://localhost:6379/0

Start Redis locally. You can install Redis directly, or run only Redis with Docker:

docker compose up -d redis

Run the app locally:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Open the interactive API docs at:

http://localhost:8000/docs

Example local request:

curl "http://localhost:8000/hosts/ipv4?domains=tmdb.org,api.tmdb.org,www.imdb.com&country=jp&token=change-me-switchfetcher-token"

Docker

Build and run:

docker compose up -d --build

Stop services:

docker compose down

Remove Redis data as well:

docker compose down -v

License

Apache License 2.0, matching SwitchHosts.

Star History

Thanks

• cnwikee/CheckTMDB
• SwitchHosts