← Back to Dashboard GitHub ↗

Help & Setup

Everything you need to deploy and configure DNS Switcher.

1 Overview

DNS Switcher is a Cloudflare Worker that lets an authenticated user instantly point a domain's DNS record to one of several preconfigured target nodes — or any arbitrary host — directly from a browser. It uses the Cloudflare DNS API to create, update, or replace A, AAAA, and CNAME records in real time.

Access is protected by Google OAuth 2.0, restricted to a single trusted email address. Sessions are stored in a signed HttpOnly cookie using HMAC-SHA256 JWTs — no external KV or database required.

2 Prerequisites

3 Environment Variables

Non-sensitive values go in the [vars] section of wrangler.toml. Sensitive values must be set via wrangler secret put in your terminal — never store them in files.

Variable Required Set via Description Example
DOMAIN Yes wrangler.toml Domain to control DNS for sub.example.com
GOOGLE_EMAIL Yes wrangler.toml Google account email allowed to log in user@gmail.com
GOOGLE_CLIENT_ID Yes secret put Google OAuth 2.0 Client ID 1234...apps.googleusercontent.com
GOOGLE_CLIENT_SECRET Yes secret put Google OAuth 2.0 Client Secret GOCSPX-...
CF_API_TOKEN Yes secret put Cloudflare API token with DNS Edit permission abc123...
NODE_NAME_n Optional wrangler.toml Display name for node n (n = 1, 2, …) Home Server
NODE_HOST_n Optional wrangler.toml IP address or hostname for node n 1.2.3.4

4 Google OAuth Setup

  1. Open Google Cloud Console → select or create a project.
  2. Navigate to APIs & Services → OAuth consent screen. Set user type to External and fill in the required fields. Under Test users, add the Google account email you intend to use — while the app is in Testing mode, only explicitly listed addresses can sign in.
  3. Go to APIs & Services → Credentials.
  4. Click Create Credentials → OAuth 2.0 Client ID.
  5. Choose Web application as the application type.
  6. Under Authorized redirect URIs, add your Worker's callback URL: 
    https://YOUR_WORKER_DOMAIN/auth/callback
    You will get the exact URL after running wrangler deploy. If you haven't deployed yet, save a placeholder here and come back to update it afterwards.
  7. Click Create. Copy the Client ID and Client Secret, then set them as secrets: 
    wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET

5 Cloudflare API Token

  1. Go to Cloudflare Dashboard → My Profile → API Tokens.
  2. Click Create Token → use the Edit zone DNS template.
  3. Under Zone Resources, select Specific zone → choose your domain.
  4. Click Continue to summary → Create Token.
  5. Copy the token — it's shown only once.

6 Deployment

Create a wrangler.toml in your project root:

name = "cf-dns-switcher"
main = "index.js"
compatibility_date = "2024-01-01"

[vars]
DOMAIN       = "sub.example.com"
GOOGLE_EMAIL = "user@gmail.com"

Store secrets securely with Wrangler (never commit these to source control):

wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put CF_API_TOKEN

Deploy:

wrangler deploy
After deploying: update the Google OAuth redirect URI to your Worker's *.workers.dev URL or your custom domain.

7 Node Configuration

Define quick-switch target nodes in the [vars] section of wrangler.toml. Nodes are numbered starting at 1 and read sequentially until a gap is found. 

[vars]
DOMAIN         = "sub.example.com"
GOOGLE_EMAIL   = "user@gmail.com"

NODE_NAME_1    = "Home Server"
NODE_HOST_1    = "203.0.113.10"

NODE_NAME_2    = "VPS Frankfurt"
NODE_HOST_2    = "198.51.100.42"

NODE_NAME_3    = "VPS Singapore"
NODE_HOST_3    = "203.0.113.55"

NODE_NAME_4    = "CDN Proxy"
NODE_HOST_4    = "cdn.example.com"

The Custom card at the bottom always lets you enter an arbitrary IP address or hostname without pre-configuring it.

8 Notes

← Back to Dashboard DNS Switcher GitHub ↗