OptiGate

The Visibility Gateway for Modern Families

Visibility to understand. Protection to secure. Guidance to grow.

Just as safety gates help protect children at home while they are learning and growing, OptiGate helps parents create safe digital boundaries online. As children mature, those boundaries can evolve, providing greater freedom while maintaining the visibility needed to guide and protect.

Protect first. Guide always. Gradually let go.

---

The gate that grows with them

When children are young, parents often place gates around the home.

Not because parents want to restrict their children forever, but because children need safe boundaries while they are learning, exploring, and growing.

As children mature, those gates gradually open. Freedom increases. Trust grows. Guidance remains.

The internet should be no different.

OptiGate helps families create healthy digital boundaries that evolve with each child, providing visibility, protection, and guidance every step of the way.

Why OptiGate?

Raising children has always required a balance between protection and independence. The name OptiGate reflects a combination of clear visibility and thoughtful protection: a family internet gateway that helps parents stay informed and engaged, set age-appropriate boundaries, encourage healthy online habits, and support growing independence.

OptiGate supports a parent's judgment rather than replacing it. Protection is the starting point; responsible freedom is the goal.

What OptiGate does

OptiGate runs on a small computer on your home network. Every device in the house is covered without installing anything on it, and everything is set from one dashboard.

• Boundaries per person. Each child has their own rules: which sites they can reach, which content categories are off limits, and when. Rules follow the person across their devices.
• Schedules that fit family life. School hours, homework time and bedtime, for one child, a group, a single device or the whole house. A parent can pause the internet, or start a schedule early for a while, at any moment.
• Visibility without spying. The Report shows which sites were allowed or blocked, for whom and when, so a conversation can start from facts. It records site names, and a page's address only where OptiGate decrypts a connection; never messages or what is on a page.
• Kids can ask. When something is blocked, a child can ask for it from the block page or the Kids Dashboard, and a parent approves or declines with one tap. Approvals can be for one child or for everyone.
• The Kids Dashboard. From https://optigate.home, each child sees what is open to them right now and what comes next, can check whether a site is allowed, follow their requests, and find what a parent newly approved for them.
• Safer search and fewer ads. SafeSearch and YouTube Restricted Mode for every device with one switch, plus ad, tracker and malware blocking through AdGuard Home.
• YouTube, curated (optional). A child watches the channels and videos a parent approved on OptiGate's own Watch page, with YouTube's own player, and can search and ask for more. Nothing changes for anyone who isn't switched on.
• Crunchyroll, show by show (optional). Approve individual shows for each child; everything else on Crunchyroll stays closed.

---

Technical overview

OptiGate is a self-hosted gateway built from Docker containers on a Linux box:

• DNS filtering with AdGuard Home covers every device: categories, SafeSearch, schedules, and ad and tracker lists.
• Network-level interception (an ARP redirect and an nftables policy engine) brings each device's traffic to OptiGate, so nothing has to be configured on the device. Identity comes from the device's MAC address, which a person's first sign-in on the captive portal ties to them.
• A Squid proxy applies per-person rules. Most sites are only checked by name and passed through untouched. Only the few sites that need page-level rules (Crunchyroll and YouTube's embedded player) are decrypted, and only on devices where a parent turned that on and installed the OptiGate certificate.
• One SQLite database holds every rule and setting. A change in the dashboard takes effect without a restart.

Requirements

• A machine running native Linux (tested on Ubuntu) with Docker and the docker compose plugin, wired to your router. Docker Desktop is not supported; see docs/server/overview.md for why.
• A home network you administer. The interception layer changes how traffic on the LAN is routed; only run it on a network you own.

Quickstart

git clone https://github.com/J1nx888/OptiGate
cd OptiGate
./setup.sh

The setup wizard asks for your LAN range, time zone, an admin username and password, whether to expose the dashboard beyond this machine, and the LAN interface and router address the interception layer will use (all prefilled from this machine). It installs the host pieces (NIC tuning, diagnostic services, conntrack settings), offers LAN-only firewall rules, then builds and starts the default containers and checks that they came up: proxy, sni-router, adguard, dashboard, dashboard-tls and kids-tls.

The interception layer is a separate, opt-in Compose profile. setup.sh deliberately doesn't start it:

docker compose --profile interception up -d

Until it runs, filtering doesn't reach the household's devices. Its arp-worker and controller refuse to start without ARP_WORKER_IFACE, GATEWAY_IP and GATEWAY_MAC in .env (setup.sh asks for them). The G1 runbook covers bringing it up on a real network, including the one command that switches it off again. Every variable is listed in docs/server/deployment.md.

Setting up a child

1. Users → Add user. The username and password are what the child types on the captive portal the first time one of their devices joins; that ties the device to them.
2. For page-level rules (Crunchyroll, YouTube): Devices, open the child's device and turn on SSL-Bump, then install the OptiGate CA certificate on that device (download it from the dashboard). That's the only step on the device itself. A device that only needs DNS-level protection skips this.
3. Approve sites and shows ahead of time, from the Report as blocks appear, or when the child asks.

Apps: OptiGate filters what reaches the network. An app that pins its certificates fails to connect rather than being filtered. Use the app's own parental controls, or your device's app controls, for those.

The dashboard

The admin dashboard is a web app at https://<box>:8787 that works on a phone too and can be installed to the home screen. It covers the Report, Users, Domains, Categories, Schedules, Devices (and device groups), Integrations (YouTube and Crunchyroll), Health (the live state of the interception layer and the Events log) and Settings, including encrypted backups.

Project layout

proxy/              Squid in intercept mode, with the per-person decision helpers
sni-router/         HAProxy in front of Squid: only sites with rules reach Squid
adguard/            AdGuard Home, set up automatically on first run
dashboard/          the Flask app: admin API, Watch page, block page, captive portal
dashboard-tls/      HAProxy for the dashboard (port 8787) and https://optigate.home (443)
spa/                the admin dashboard, the Watch page and the Kids Dashboard (React)
controller/         the interception layer's control loop (Python)
phase3/             Go daemons: arp-worker and nftables-manager
common/             shared Python used by the proxy, dashboard and controller
defaults/           first-run seed data
nic-tuning/, conntrack-tuning/, diagnostic-poller/
                    host services: network tuning and the Health page's diagnostics

The technical reference, by area (server, dashboard, frontend, features, database, security, testing), starts at docs/project.md. Good places to begin: YouTube (and getting a YouTube API key), Crunchyroll, DNS filtering, devices and identity and the security overview.

Backups

Settings → Backup & restore downloads the household's configuration: people, devices, rules, schedules and integrations. A full backup also holds the CA certificate and the integration keys, encrypted with a passphrase you choose (how backups protect secrets). Keep backup files private either way.

Testing

pip install -r requirements-dev.txt -r dashboard/requirements.txt
pytest

Run from the repository root with Python 3.12; nothing in the suite needs Docker or the network. The Go daemons have go test ./... in each phase3/ module, and the dashboard has yarn verify and yarn e2e in spa/. docs/testing/overview.md covers every layer.

Security

OptiGate holds a certificate authority and a household's rules, so its defaults are conservative: the dashboard listens on the box itself unless you choose otherwise, sign-in passwords are stored only as hashes while the AdGuard password and the YouTube API key are stored encrypted, and the interception layer fails open rather than cutting the house off the internet. The security overview describes the threat model and the accepted trade-offs.

To report a vulnerability, please don't open a public issue; see SECURITY.md.

License

OptiGate is free software under the GNU Affero General Public License v3.0 (AGPL-3.0). In plain terms:

• You may use, study, change and share it, including for your own household.
• If you give a copy to someone else, modified or not, you must pass on the source code and the same license.
• If you change OptiGate and let other people use your changed version over a network (for example, a hosted service), you must offer them its source code too.

The license text in LICENSE is what counts; this summary is not legal advice.

OptiGate runs some separate programs in their own containers, each under its own license: Squid and HAProxy (installed from Debian's packages) and AdGuard Home (its official image). The dashboard's icons come from Font Awesome Free (icons CC BY 4.0, code MIT, https://fontawesome.com/license/free).