Skip to content
BranchesTags

Repository files navigation

Synkin — Test Localhost on Android over USB

Instantly preview your local web apps on Android — over USB.

npm License: MIT Platform Downloads

Install · Usage · Visit our website · Report an issue

Synkin is a free, open-source npm CLI for testing localhost websites on Android over USB, using Android Debug Bridge (ADB Reverse) instead of Wi-Fi, a local IP address, or a public tunnel.

It maps your Android device's localhost directly to your computer's localhost over a USB cable. Because your app keeps running on localhost — not a LAN IP or tunnel domain — your existing Google OAuth, Firebase Authentication, Clerk, Auth0, Supabase Auth, cookies, sessions, WebSockets, and backend APIs continue working exactly as they do on desktop, with no CORS changes and no new OAuth redirect URIs.

Synkin automatically detects React, Vite, Next.js, Express, FastAPI, Flask, Django, and static HTML projects, forwards the right ports, and launches Chrome on your Android device the moment it's ready — no Wi-Fi, no firewall rules, no manual IP configuration.

npm install -g synkin
synkin run

🎬 Demo

Synkin demo showing localhost opening on Android over USB

For a visual walkthrough, check out the website.

Contents

Features
🚀 One-command setup Run a single command and the bridge configures itself.
🔌 USB-only connection No Wi-Fi, no shared network, no exposed ports.
📱 Automatic Chrome launch Opens your project on the device the moment it's ready.
🔍 Automatic project detection Recognizes your framework by scanning the current directory.
⚡ Automatic port discovery Finds the ports your servers are running on — nothing to specify.
🔄 Frontend + backend together Bridges both at once, in a single run.
🌐 Works with localhost APIs Backend requests are tunneled through ADB Reverse.
🧹 Cleans up on exit Disconnect the cable or stop Synkin and everything unwinds automatically.
💻 Cross-project support Use it in any project directory, no per-project config.

Authentication support

Because Synkin preserves the browser origin as localhost, authentication providers configured for localhost keep working without any changes — no new OAuth client IDs or redirect URIs required.

Tested and working with:

  • Google OAuth
  • Firebase Authentication
  • Clerk
  • Auth0
  • Supabase Auth
  • Auth.js
  • Passport.js
  • Better Auth

API support

Synkin automatically forwards frontend and backend ports using ADB Reverse, so your app keeps calling the same URLs it already uses locally — for example http://localhost:3000/api or http://localhost:8000.

REST APIs, GraphQL APIs, WebSocket servers, and local development backends all continue working exactly as they do on desktop, with no URL or CORS changes required.

Why Synkin

Testing on a real Android device usually means doing one of the following first:

  • Finding your local IP address
  • Connecting both devices to the same Wi-Fi network
  • Opening firewall ports
  • Updating backend API URLs
  • Reconfiguring CORS
  • Adding new Google OAuth origins
  • Spinning up a temporary tunneling service

Synkin removes all of that by using ADB Reverse over USB. Your Android browser opens http://localhost:5173 — not http://192.168.x.x:5173, and not https://random-tunnel.example.com — so your app behaves exactly like it does on your desktop.

Before Synkin With Synkin
✕ Find your local IP address ✓ USB only
✕ Disable your firewall ✓ localhost just works
✕ Configure the LAN ✓ Automatic device discovery
✕ Change backend URLs ✓ Chrome launches on its own
✕ Reconfigure CORS ✓ Backend requests work out of the box
✕ Reconnect after every restart ✓ Zero configuration

Requirements

Verify ADB is installed:

adb version

Verify your device is recognized:

adb devices

Expected output:

List of devices attached
2201116PI    device

How it works

Synkin never exposes your application to the internet. Instead, it:

  1. Detects your running development server
  2. Detects your connected Android device
  3. Creates ADB Reverse port mappings
  4. Opens Chrome automatically
  5. Lets Android access your computer's localhost directly

Because Android still accesses your application through localhost, the browser origin remains http://localhost. Existing authentication, cookies, sessions, CORS policies, backend APIs, and WebSocket connections continue working exactly as they do in your desktop browser.

Installation

Install globally with npm:

npm install -g synkin

Verify the installation:

synkin --version

To update later:

npm update -g synkin

Usage

1. Start your frontend

npm run dev

2. Start your backend (optional)

npm run dev

3. Connect your Android phone via USB

4. Run Synkin

synkin run

Synkin will then:

  • Detect your Android device
  • Discover your running project
  • Detect frontend and backend ports
  • Configure ADB Reverse
  • Launch Chrome automatically
  • Open your project on the phone

Typical workflow

# Terminal 1
cd frontend
npm run dev
# Terminal 2
cd backend
npm run dev
# Terminal 3
synkin run

That's it — your project is live on-device.

Supported frameworks and tools

Frontend Backend Database
React Express.js MongoDB
Vite NestJS PostgreSQL
Next.js FastAPI MySQL
Angular Flask SQLite
Static HTML Django

Database support means Synkin doesn't interfere with your backend's own connection — as long as your backend server is running, its database connection works exactly as it would locally.

If your development server listens on a localhost port, Synkin can usually bridge it automatically.

Synkin also works with most other local development servers and stacks, including:

React Scripts · Vue · Svelte · Remix · Astro · Angular CLI · NestJS · Laravel · Spring Boot · Node.js HTTP Server · Python HTTP Server · Bun · Deno · Prisma · Firebase · Supabase · REST APIs · GraphQL · WebSockets

More frameworks will be added in future releases.

Project detection

Synkin automatically detects supported projects by scanning the current directory — no configuration required.

Detected project types 
React
Vite
Next.js
Angular
Express
NestJS
FastAPI
Flask
Django
HTML

Static HTML projects

Synkin also supports simple static sites. Serve your files however you like:

python -m http.server 5500
npx serve .

Then run:

synkin run

Notes for Vite users

Your Vite server must be reachable through ADB Reverse. If it's only listening on 127.0.0.1, Android Chrome can't reach it through the bridge — enable server.host in vite.config.ts:

server: {
  host: true,
},

Perfect for

  • Mobile responsive testing
  • Google OAuth testing
  • Camera API testing
  • Touch interaction testing
  • PWA testing
  • Android Chrome debugging
  • Backend API development
  • Full-stack application development

Troubleshooting

Device not detected

Check the connection:

adb devices

Make sure these are enabled on the device:

  • USB debugging
  • File transfer mode

Chrome doesn't open

Confirm Google Chrome is installed on the Android device.

Project not found

Run Synkin from inside your project folder:

cd my-project
synkin run

Backend requests fail

Make sure your backend server is running before starting Synkin.

Chrome says "This site can't be reached"

Make sure your vite.config.js includes:

server: {
  host: true,
},

FAQ

How is Synkin different from ngrok or Cloudflare Tunnel?

Unlike public tunneling services, Synkin never exposes your application to the internet. It uses Android Debug Bridge (ADB Reverse) to map your Android device's localhost directly to your computer's localhost over USB, preserving the original localhost browser origin.

Does Synkin work without Wi-Fi? Yes. Synkin only requires a USB connection and ADB.

Does Synkin expose my application to the internet? No. Everything stays on your local machine.

Does Google OAuth continue working? Yes. Since Android accesses your application through localhost, existing localhost OAuth configurations continue working unchanged.

Do I need to change backend URLs? No.

Does Synkin modify my project? No. Synkin only configures temporary ADB Reverse mappings — it never edits your project files.

Release notes

Full version history and changelogs are published on the Synkin website.

Contributing

Contributions, suggestions, and bug reports are welcome. If you find a bug or have an idea for an improvement, open an issue.

License

Released under the MIT License.

Made with ❤️ by Samarpan ~ owsam22

About

Test localhost websites on Android over USB using ADB Reverse. Free npm CLI for React, Vite, Next.js, Express, FastAPI, Flask, Django and HTML. preview website on android

owsam22.github.io/synkin-page/

Topics

adbadb-reverseandroidbackendhtmllocalhostnpmowsam22reactsamarpanusbweb-developmentwebsitewebsite-testing

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Packages

Contributors

Languages