KidGuard v0.9.48

KidGuard guide

Install it on your child's Android phone, open the parent page, then keep managing it when the child is out. Follow the steps; everything can be undone.

Get KidGuard child's phone Parent app your phone

Install on the child's phone

  1. Install the APK and open the app. No need to remove accounts, no setup yet. These already work: the kid launcher (opt-in on the phone), Dọn máy (debloat) Beta (only needs wireless-debugging pairing; the app runs pm disable-user against the phone itself), and Bố mẹ quản lý trên máy này (the parent page on the child's phone, in preview mode: features that need more permissions are greyed out with a note saying which one).
  2. Set the parent PIN: the pairing form (step 5) makes you set one. It protects the page on this phone and allows pairing more parent phones.
  3. Grant permissions as needed, following the feature and permission table: accessibility, usage access, device admin, location…
  4. Optional, strongest: Device Owner (ways A-D below). Only this step needs every account removed from the child's phone first.
  5. Pair the parent's phone or browser (home Wi-Fi or relay, see Away from home).

There are five ways to install; pick one. Ways A to D make KidGuard the phone's Device Owner (the Android role a company uses for work phones): it can lock apps and can't be removed, no root needed. Way E skips this but is weaker.

Only for Device Owner (ways A-D): Android only lets an app become Device Owner while the phone has no accounts. KidGuard keeps app accounts; phone accounts must be removed first.

Phone accounts (Google, Samsung, Xiaomi, Oppo/HeyTap…): on the child's phone open Settings → Accounts and remove them. Sign back in after setup: everything comes back.

Keep apps signed in (Zalo, Facebook, Telegram…): automatic. KidGuard turns those apps off for a moment, the phone restarts once (about 1 minute), setup finishes, and the apps are turned back on. Way A (QR) does not need it: a new phone has no accounts yet. Ways B, C, D all do it; the on-phone setup carries on after you unlock the screen and tells you with a notification. If a phone account is there, KidGuard stops and names the account to remove.

By hand (if needed): adb shell pm disable-user --user 0 <package>, wait 15 seconds, adb shell sync, adb reboot, wait about 30 seconds after the phone is up, set up Device Owner, then adb shell pm enable <package>. Which app owns which account: adb shell dumpsys account.

A. On the phone itself Recommended

Needs: Android 11+, Wi-Fi. No computer. Phone accounts (Google, Samsung…) must be removed first: KidGuard stops and says which ones.

  1. Download the APK on the child's phone, install it and open KidGuard.
  2. Tap Full setup without a computer (Android 11+).
  3. Turn on Developer options: open About phone and tap Build number 7 times.
  4. In Developer options, turn on Wireless debugging and allow this Wi-Fi.
  5. Back in KidGuard, tap Show the code box in a notification. Then in Wireless debugging tap Pair device with pairing code.
  6. Pull down the notification shade, tap Enter pairing code and type the 6 digits shown.
  7. KidGuard does the rest, then turns Wireless debugging off again.

The code goes into a notification because the pairing dialog closes when you leave Settings. If the notification doesn't show, type the code in KidGuard itself.

B. Scan a QR code

Needs: a new or factory-reset phone with stock-like Android (Pixel, Samsung, Nokia…).

  1. Turn the child's phone on and stop at the welcome screen.
  2. Tap 6 times on an empty spot. The phone opens a QR scanner.
  3. Scan the setup QR code (open it on a computer or another phone).
  4. The phone downloads KidGuard over Wi-Fi and sets it up.
  5. Open KidGuard and finish the short checklist on screen.

Some skins drop the 6-tap screen (e.g. Oppo / Realme ColorOS on Android 8–9). Use way C there.

C. Computer and USB cable

Needs: a computer with Chrome or Edge, a USB cable. No adb to install. About 3 minutes.

  1. On the child's phone: remove the phone accounts (Google, Samsung, Xiaomi, Oppo…) in Settings → Accounts. Leave app accounts alone.
  2. Turn on Developer options: Settings → About phone, tap Build number 7 times.
  3. In Developer options, turn on USB debugging. Xiaomi / Redmi / POCO: also turn on USB debugging (Security settings) and Install via USB.
  4. Plug the phone into the computer and open the installer page in Chrome or Edge.
  5. Press the connect button and pick the phone in the dialog. On the phone tap Allow (tick “Always allow from this computer”).
  6. Press the install button. When it's done the page shows the address for the parent.

D. Command line

Needs: macOS, Linux or Windows, a USB cable.

  1. Prepare the child's phone as in way C, steps 1–3, and plug it in.
  2. Get the source on the computer (or just the setup.sh / setup.ps1 file).
  3. Run:
    git clone https://github.com/HoangTran0410/kidguard && cd kidguard
    scripts/setup.sh
    
    # Windows
    powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
  4. The script downloads adb if it is missing, and the latest KidGuard release (SHA-256 checked) if it finds no APK. Add -y to skip the questions.
  5. It runs 8 steps: install the app, set Device Owner, grant usage access and secure-settings access, turn on accessibility, allow background running, open the app, print the parent's address.

E. Basic mode Weaker

Needs: any Android 8+. No computer, accounts can stay. For old phones with no QR screen and no computer or cable.

  1. Install the APK, open KidGuard, follow the To do list on the screen.
  2. Turn on each item in order: device admin, accessibility, usage access, location (choose Allow all the time), notifications, battery.
  3. Each button opens the right system screen: turn the setting on, then press Back.

Why it is weaker: blocked apps are closed back to the home screen instead of greyed out.

  • Not available: family DNS, blocking app installs / USB debugging, locking airplane mode / location / clock, reboot, Tailscale.
  • A child who boots into Safe Mode or turns accessibility off stops the blocking. The parent page shows a red warning and the parent app notifies.

You can switch to Device Owner later with way A, C or D (accounts removed, like a fresh install). Rules and pairing are kept.

Open the parent page

The last setup screen on the child's phone shows a 6-digit pairing code and a QR code for 10 minutes. Later: hold Bố mẹ: hiện mã ghép (parents: show pairing code) for 5 seconds on the KidGuard screen.

  1. On your phone (same Wi-Fi as the child's), scan the QR with the camera. The page opens with the code filled in.
  2. Or open a browser at http://<child phone IP>:8770 and type the 6-digit pairing code.
  3. Set a parent PIN in the pairing form. Without it the child's phone refuses to pair another browser.
  4. Sign back in to the accounts on the child's phone (if you removed them) and unplug the cable.
  5. Xiaomi, Oppo, Vivo, Samsung: on the child's phone tap Battery / autostart settings and let KidGuard run in the background.
  6. To manage when your child is out too: see Away from home.

Oppo / Realme / OnePlus (ColorOS): open Recents and pull the KidGuard card down to lock it (padlock icon). In Phone Manager allow KidGuard to autostart and run in the background. Swiping KidGuard away in Recents on ColorOS stops the app completely.

Finding a setting: on the parent page, tap Find a setting at the top (or press /) and type a few letters, like relay, bedtime, wifi. This guide says “search …” instead of a menu path, since menus can move.

First time: 4 quick steps. Right after pairing the page walks you through starting level (Light, Balanced or Strict), your top apps (allow, normal or block), bedtime and daily limit, and what the kid sees. Nothing is saved until Done. Redo it any time: search set up again.

On home Wi-Fi the page is plain HTTP: use it only on networks you trust. Each browser pairs once with the 6-digit code; pairing more needs the parent PIN.

Parent app (Android)

The browser is enough to manage everything. The parent app adds notifications (SOS, more-time requests, accessibility turned off, lost connection) and shows the last data when the child's phone is offline.

  1. Download the parent app and install it on your phone.
  2. Open it and tap Add kid's phone.
  3. At home: type the address shown on the child's KidGuard screen, then the 6-digit pairing code (hold Bố mẹ: hiện mã ghép for 5 s if you see none).
  4. Away from home: tap Scan QR and scan the code on the child phone. Only KidGuard links are accepted.
  5. The other parent: on your page search relay and tap Invite another parent. They scan the QR (or open the link) and type a name. The invite works once and ends after 10 minutes.
  6. Each parent has their own access: that section lists who has it, with rename and remove. Commands and rules show the sender's name in the child's log. A browser asks the family PIN again every 12 hours.
  7. Two kids or more: Overview shows every kid on one page.

Easier: the Telegram bot delivers SOS and more-time requests at once, no app or build needed.

A time request notification has +15 / +30 min and Decline buttons right on it. The app checks about every 15 minutes. For SOS in seconds (through the Worker and Firebase) you build the app yourself: see the README.

Notifications check: the app has a health card (Settings) that says if alerts can reach you (permission, channels, battery saver, last check) and fixes each in one tap. Offline phones show “offline since HH:mm”.

Parent on an iPhone: there is no app, the browser (Safari) is enough.

Away from home

At home the page talks to the child's phone over Wi-Fi, nothing to set up. When the child is at school or out there are 3 free ways; use one or several. The shared relay is already on from pairing, so the page opens from anywhere even if you do nothing.

  • Just alerts and quick taps (extra time, lock, location): the Telegram bot.
  • Everything like at home (live screen, listen around): Tailscale.
  • Only a browser: the relay (already on; make your own if you don't want data going through the author's server).
Telegram botTailscaleRelay
Setup~2 min: make a bot, paste its token~5 min, once: Tailscale app on the parent's phone, paste one keyNone (shared relay is on). Your own: ~3 min on a computer
Used withThe Telegram app, buttonsThe parent page (Tailscale app on)The parent page, any browser
Speed~1 secondInstantUsually a few seconds (if the live link drops: ~20 s, screen off ~60 s)
Screen / listenScreenshot, 10–60 s recordingLive screen, live listenLive screen, no listen
SOS, more-time requestsArrive at once in TelegramIn the page / parent appIn the page / parent app
Data goes throughTelegram's serversNobody (end-to-end encrypted)Shared: the author's Cloudflare. Your own: only your account
NeedsInternet on the child's phone. One bot per childDevice Owner (not in basic mode)Nothing
Child seesNothing (a notice while recording)A key icon in the status bar (VPN)Nothing

The Telegram bot, Tailscale and your own relay are all turned on while at home, in the parent page: search telegram, search tailscale or search relay.

Telegram bot Easiest

Control and get alerts right in Telegram: status, extra time, lock, location, screenshot, block apps with buttons. SOS, "more time" requests (with Allow / No buttons) and wrong PINs (with a photo) arrive by themselves. No Tailscale or relay needed: the child's phone runs the bot. One bot per child.

  1. Create a bot (1 minute). On the parent's phone open @BotFather in Telegram, tap Start, send /newbot. Send a name (e.g. Bin's home), then a username ending in bot (e.g. binshome_kidguard_bot; taken? add digits).
  2. Copy the token. BotFather answers with a line like 123456789:AAH…: tap it to copy. Long-press the whole message → Copy works too. Keep the token secret.
  3. Paste it in the parent page. search telegram, paste into the token box (the whole message is fine, the page picks the token out), tap Connect.
  4. Link. The page shows Open Telegram and link and a QR code. Tap it (or scan the QR with your phone's camera), Telegram opens the bot, tap Start. The bot says hello and shows the Menu.
  5. Add people (mum, dad, grandparents, up to 5): tap Other code and send them the link.

Use it: tap 📋 Menu for buttons, or type commands (/status, /bonus 30, /lock, /locate…); /requests lists open requests, /lost turns lost mode on / off, /quiet sets the alert level; /code sends the 6-digit unlock code to read out to your kid (no Authenticator app needed); /help lists them all, /lang switches English / Tiếng Việt. Release, unpair and clear data are not possible over Telegram.

Two children?

Make two bots (e.g. Bin's home, Na's home), each pasted on that child's page. One bot runs on one child's phone only.

“Wrong token” or “used somewhere else”?

Copy BotFather's whole message again and paste it. “Used somewhere else” means the bot belongs to another phone: make a new bot for this child. Token leaked? Send /revoke to BotFather for a new one and paste it again.

Tapped Start, the bot says nothing?

A link code works for 15 minutes: tap Other code. The child's phone must be online (the bot runs on it).

Where do messages go?

Through Telegram's servers (not end-to-end encrypted). The token stays on the child's phone. Turn it off: search telegram → Turn off, the phone forgets the token.

Tailscale Most complete

The child's phone installs Tailscale itself and joins your private network. No Cloudflare needed. Needs Device Owner (not in basic mode).

  1. On your phone: install the Tailscale app and sign in with Google / Apple / Microsoft. This also makes your free Tailscale account.
  2. Open the Keys page → Generate access token → Generate → copy it.
  3. At home (same Wi-Fi as the child's phone), open the parent page: search tailscale.
  4. Paste the key into the tskey-api-… / tskey-auth-… box, optionally name the phone (e.g. kid-an), press Turn on.
  5. The child's phone downloads the official Tailscale app (SHA-256 checked), installs it silently, joins your network and hides the app. About a minute.
  6. The card shows Connected, an address like http://100.x.y.z:8770 and never expires.
  7. On your phone (with Tailscale on), open that address. Several kids: add each address with Add kid's phone.

Access token or auth key?

  • API access token (tskey-api-…), recommended: the child's phone makes its own one-off key and turns off Tailscale's 180-day key expiry for itself. The token is only used during setup, then dropped, never stored.
  • Auth key (tskey-auth-…): also works, but you turn off the expiry by hand once. Open the Machines page → the child's phone row → ⋯ → Disable key expiry. Otherwise Tailscale signs the phone out after 180 days. The parent page reminds you.

Good to know

  • Turning it on or changing the key only works at home. The key stays on the child's phone and never goes through the Worker.
  • The child can't turn the VPN off, change VPN settings or uninstall Tailscale. The safe-DNS filter keeps working.
  • To stop: press Turn off and remove Tailscale (or Remove controls). Then delete the phone on the Machines page, since an uninstalled app can't log itself out.

Relay (Cloudflare Worker)

Already on: after pairing the page uses KidGuard's shared relay and opens from anywhere (link: search relay on the page). Your child's state, location and rules pass through the author's Cloudflare account, and the free quota is shared by everyone. Don't want that: make your own relay as below, or turn the relay off in Settings.

Make your own relay

A small Cloudflare Worker in your own free Cloudflare account relays commands, state and the live screen. Screen frames stay in the Worker's memory only, never stored. The parent's phone only needs a browser.

Needs: a computer with Node.js 18+. The Cloudflare account can be made for free at login.

  1. On the computer, run:
    git clone https://github.com/HoangTran0410/kidguard && cd kidguard
    scripts/relay.sh
    
    # Windows
    powershell -ExecutionPolicy Bypass -File scripts\relay.ps1
  2. The script does 3 steps: installs its tools (about a minute the first time), opens the Cloudflare login in your browser (if you're not logged in), then deploys.
  3. A new account may be asked to pick a workers.dev subdomain: answer it, it becomes part of the relay address.
  4. It prints the address: Relay ready: https://kidguard.<you>.workers.dev.
  5. At home, open the parent page: search relay, the own relay (Cloudflare Worker) part. Paste the address, press Turn on.
  6. The page shows a remote-control link. Open it on your phone (keep it safe, don't share it), or paste it into the parent app.
  • Update: run the script again. Remove it from your account: scripts/relay.sh --delete (Windows: -Delete).
  • Free plan: 100,000 requests a day, one kid's phone uses about 4,300. Commands usually arrive in a few seconds. Listen around doesn't work through the relay.

Shared relay

Address https://kg-relay.99-hoangtran.workers.dev, on by default. The free daily quota is shared by everyone, so on a rare day it can run out: then use the Telegram bot, Tailscale or your own relay.

Amazfit watch (Zepp OS)

The watch app (the watch/ folder) lets a parent see time left, answer requests, lock, ring and see the location from the wrist. Connect it like pairing a TV: open KidGuard on the watch and tap Connect to get a 6-digit code, then on the parent page search watch, enter the code and tap Connect. The relay must be on for that kid. The code expires after 10 minutes and the watch shows a new one. Without a code you can still paste the relay link in the Zepp app's settings page.

Features

All in the current release, no paid tier.

Time

Daily limit
One number, or one per weekday. When time is up every app (except “Always allowed”) locks until midnight. +15 / +30 / +60 min for today.
Bedtime, schedules
Bedtime every day, plus windows on chosen days (school hours Mon–Fri); can cross midnight.
Heads-up before locking
The child gets a notification 5 min and 1 min before the limit, bedtime or a schedule locks the phone.
More time always works
Approve a request during bedtime or school hours: the phone opens for N minutes, then locks again. Tap End to lock early.
Bedtime per night, +1 min
A separate bedtime for each night (school nights differ from weekends). When it locks, the child can take +1 minute once per lock to save their work. Can be turned off.
Pause now
30 min, 1 h, or until 6 am.
Ask for more time
15 / 30 / 60 min plus a reason; the parent approves or declines.
Chores
The parent lists chores (“Wash the dishes +20 min”); the child picks one when asking. Approve with a note if you like.
Unlock code
6 digits from Google Authenticator, no network on either phone. The child gets 15–120 min free of limits; each code works once.
Rule templates
School day, Weekend, Summer holiday, Exams, or save your own. Apply to one kid or several.

Apps

Per app
Normal, N minutes a day, Block, or Always allowed. Select many to change them at once.
App groups
One shared daily limit for a group (“Games”, “Social”) and/or hours when it may be used.
New apps
Optionally locked until a parent approves them.
Lighter phone
Hide the maker's preinstalled apps the child doesn't use, see the heaviest apps, clear an app's data. Needs Device Owner.
Updates itself
Once a day the child's phone checks GitHub releases, downloads the new APK and checks its SHA-256. Off or update now in Settings.

Location and safety

Location
Locate now, location forced on (the child can't turn it off), 7-day history on an OpenStreetMap map.
Zones
Home, School… with a radius: you're told when the child arrives or leaves.
SOS
A red button on the child's phone: the parent page shows the time and a fresh location; the parent app notifies.
See the screen
The child's screen live (Android 11+, ~3 fps). The child is told the parent is viewing.
Remote control
Tap, swipe, long press, Back / Home / Recents, type text.
Listen around
At most 10 min at a time, home Wi-Fi or Tailscale only. The child always knows: a beep, a notification, Android's mic dot.
Lost mode
Where tab: turning it on locks the phone at once and again on every unlock, shows your message + number on the lock screen, locates every 5 min and rings 5 min in every 15. Turn it off and everything goes back. Also alerts on a SIM change.
Alert levels
Only SOS, lost, tamper and requests make noise; the rest arrive quietly. Telegram: /quiet picks all / important / SOS only per person. The parent app says “offline since HH:mm” and skips the child's bedtime.
Alerts
Arrived / left a zone, battery at 15 %, a new app installed, the clock changed.

Looking back

History
Screen time for 7 days, top apps per day, a weekly report per kid.
All kids
Overview: a card per kid, every kid's location on one map, 7 days side by side.
Child's rules
The child sees their own rules and a log of what the parents changed.
Languages
English and Vietnamese in the parent page and both apps.

Kid home screen

Gestures
Hold an icon: a menu over a dimmed screen, with Edit Home Screen. Drag an app onto another to make a folder. In edit mode, the minus badge removes (it asks first); pick several to group or remove at once.
Folders, library
Folders open from their icon; hold to re-arrange. App Library on the last page: suggestions, recently added, categories, search.
Widgets
Clock, month, time left, timetable (morning/afternoon, bell times, whole week), chores, notes, battery, weather, lock screen; other apps' widgets too.
“Today” page
Swipe right from page 1. SOS and Call always sit on top. Cards: Right now (class now, time until bedtime), Screen time (ask for more), Tomorrow (from 5 pm), chores, notes, Files with parents (the kid can send a file from here). Choose cards at the end; turn the whole page off in Customize.
This week
“Your week” card on Today: days within the daily limit, the current run, finished lists. It hides when there is nothing to celebrate.
Requests
One open request per kid: the child sees waiting and can Remind, then the last answer. The child can also ask to open a blocked or new app. You answer with N/2, N or 2N minutes, on the page, in the parent app or in Telegram (/requests); once answered it updates everywhere. Unanswered requests expire at midnight.
Customize
Hold an empty spot on the home screen: Widgets, Edit Home Screen, Customize. In Customize: wallpaper (blur, dim), columns, icon size (rows stay the same), icon shape (circle, square, squircle), label size, font, light/dark, accent colour, notification dots, effects Full / Light / Auto. Undo appears right under what you changed.
Saved layouts
Save current layout (up to 5, named): pages, dock, look and photo wallpaper. Tap one to switch the whole home, with undo. Stored on the phone only.
Control center
Swipe down on the right half of the home screen: Wi-Fi, Bluetooth, airplane, data, torch, rotation, Do Not Disturb, brightness, volume, now playing, Study. The left half opens notifications.
Study mode
The kid starts it: only study apps stay on the home screen, Do Not Disturb on if allowed. Apps the parent blocked stay blocked.
Hidden apps
In the App Library, ⋮ next to search: every hidden app with the reason (blocked, waiting for OK, study time...). A page KidGuard closes always says why in a short message.
No parental control?
This launcher has its own app: KidGuard Home (under 1 MB). Fits any phone, needs no parent and no special permissions; SOS, time requests, chores and files are left out. Open it and tap Fix on the banner to make it the home screen.
Already have KidGuard?
No need for KidGuard Home: the launcher is built in. Install KidGuard later and the layout, notes, timetable and wallpaper move over by themselves (KidGuard Home 0.9.10 or newer); other apps' widgets must be added again.
Xiaomi, Redmi, POCO
With a home screen that is not Xiaomi's, navigation turns into 3 buttons: the system does this and no setting keeps gestures. Pick Xiaomi's home screen again to get gestures back.

Hard to break

Tamper-proof
Blocks uninstall, force stop, factory reset from Settings, Safe Mode, new users, changing the clock, airplane mode. A watchdog restarts it.
Factory reset protection
Device Owner, Android 11+. After a reset from recovery the phone asks for the parent's Google account. Needs that account's numeric ID (not the email); the page shows how to get it. A wrong ID can lock the phone for good after a reset. Turned off when you remove controls.
PIN tries left
A wrong PIN on the child's phone says how many tries are left. Forgot PIN? shows how to reset (24 h wait, with an alert).
Command receipts
Every command shows sent, then ran HH:mm, refused or expired (with Resend). A wrong PIN over the relay is not remembered.
Optional
Family DNS filter (AdGuard / Cloudflare / CleanBrowsing), block installs, block USB debugging.
Commands
Lock the screen, ring, full-screen message, restart the phone.

Locked apps use Android's own mechanism: the icon turns grey and opening it says the parent paused it.

Child on an iPhone / iPad

There is no KidGuard for iOS: Apple doesn't let third-party apps see the screen, control the phone or lock other apps. Use what is built in and free:

  • Screen Time + Family Sharing: limits, downtime, app limits, adult-site filter, purchase approval, “ask for more time”, managed from the parent's iPhone.
  • Find My: the child's location.

Child on Android, parent on an iPhone: manage it from the iPhone's browser.

Remove KidGuard

  1. Parent page: search danger → Remove controls…
  2. Every app is unlocked and every restriction lifted. If Tailscale was on, it is removed too.
  3. Uninstall KidGuard like any app.

Troubleshooting

“App blocked to protect your device” (Play Protect)?

Play Protect blocks apps installed from a browser or file manager when they use accessibility. On the child's phone: Play Store → your avatar → Play Protect → ⚙ → turn off Scan apps with Play Protect. Install and set up KidGuard, then turn it back on. QR setup is not affected (the phone downloads the app itself).

No 6-tap spot on the welcome screen?

Some skins drop that screen (e.g. Oppo / Realme ColorOS on Android 8–9). Use the computer and USB cable.

Phone older than Android 11 can't set itself up?

Way A needs Android 11+. Use a computer (way C or D), factory reset and scan the QR, or use basic mode.

The parent page won't open?

Check the address on the child's KidGuard screen (default port 8770). Your phone must be on the same Wi-Fi, or the same Tailscale network, as the child's phone.

Can the DNS filter cut the Internet?

No. If the filter's host is refused, or the network has Internet but DNS-over-TLS is blocked for 90 seconds, KidGuard falls back to normal DNS for 30 minutes and the parent page says why.

Why do some apps show black when viewed remotely?

Apps that mark their screen secure (banking…) always show black.

Can the child remove it?

Not from Settings. A factory reset from the hardware keys (recovery) still works: KidGuard is gone and the parent page shows “disconnected”.

Limits on Android 8–10?

Live screen and remote control need Android 11+. On Android 8–10 the child can force stop KidGuard (it starts again on reboot).

Another bug or an idea?

Post it on GitHub Issues. Technical details: docs/protocol.md.