██████╗ ██╗      █████╗  ██████╗██╗  ██╗ ██████╗ ██╗   ██╗████████╗
██╔══██╗██║     ██╔══██╗██╔════╝██║ ██╔╝██╔═══██╗██║   ██║╚══██╔══╝
██████╔╝██║     ███████║██║     █████╔╝ ██║   ██║██║   ██║   ██║
██╔══██╗██║     ██╔══██║██║     ██╔═██╗ ██║   ██║██║   ██║   ██║
██████╔╝███████╗██║  ██║╚██████╗██║  ██╗╚██████╔╝╚██████╔╝   ██║
╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝    ╚═╝
                  ██╗  ██╗██╗████████╗
                  ██║ ██╔╝██║╚══██╔══╝
                  █████╔╝ ██║   ██║
                  ██╔═██╗ ██║   ██║
                  ██║  ██╗██║   ██║
                  ╚═╝  ╚═╝╚═╝   ╚═╝

Blackout Kit (blackout-kit) — Network Security & Bypass Toolkit

A network security and bypass toolkit for Windows and Linux. 17+ engines, MCP-integrated diagnostics, country-aware routing, smart config rotation, encrypted vault, and self-healing crash recovery.

Country profiles: 🇮🇷 Iran · 🇷🇺 Russia · 🇨🇳 China · 🇮🇶 Iraq · 🇬🇧 United Kingdom · 🇺🇸 United States · 🇪🇺 Europe

---

Table of contents

• What Blackout Kit is
• Choose your guide
• Current feature map
• Platform support
• Engine map
• Installation
• Quick start
• Zero-argument launcher
• Command map
• Security, privacy, and safety boundaries
• Data and local state
• MCP server
• Desktop GUI
• Split tunnel
• Troubleshooting
• Roadmap and contributing
• Disclaimer

---

What Blackout Kit is

Blackout Kit is a local coordinator for bypass engines and user-supplied proxy or VPN configurations.

It does not operate remote VPN or proxy servers. Instead, it helps users:

• launch locally available runtimes
• manage saved proxy configuration URIs
• apply system-proxy settings when an engine exposes one
• run targeted network recovery after crashes
• inspect local readiness before connection startup
• switch between documented local security profiles
• use a Windows desktop GUI or the CLI for the same core workflows

Design goals in the current release line:

• Windows-first breadth — the broad engine catalog and desktop GUI live on Windows.
• Linux support with strict scope — Linux supports only the managed XRay, TUN, Hysteria2, and TUIC paths.
• Local-first safety — readiness, route ranking, status, and most diagnostics distinguish local state from remote reachability.
• Targeted recovery — Blackout Kit removes only its own detected proxy, route, adapter, firewall, and cache state unless the user explicitly requests broader repair.
• Accurate claims — modes and profiles tune local behavior; they do not guarantee anonymity, bypass success, or resistance to traffic analysis.

---

Choose your guide

If you are here to use Blackout Kit, start with the user guide:

• User Guide

If you are here to maintain, package, test, or contribute to Blackout Kit, start with:

• Contributing Guide

The README stays high-level. The two guides go deeper in separate directions on purpose.

---

Current feature map

Blackout Kit 1.1.1 currently includes:

• Typer-based public CLI with backward-compatible delegation into the proven command dispatcher
• Zero-flag launcher flow that opens the GUI first and falls back to an interactive terminal menu
• Desktop GUI built with CustomTkinter
• MCP stdio server for AI clients with a constrained, documented tool surface
• Route recommendation dashboard based on local readiness, platform support, saved protocols, settings, country profile, and saved health history
• Local readiness checks that do not contact remote hosts or mutate state
• Targeted post-crash recovery on Windows and Linux
• Machine-bound encrypted local vault for saved proxy URIs and supported VPN secrets
• Windows system-proxy bypass patterns stored through ProxyOverride
• Linux endpoint-scoped kill switch with nftables or iptables fallback
• Country profiles for Iran, Russia, China, Iraq, United Kingdom, United States, and Europe
• In-app help system for terminal users
• Local SHA-256 fingerprints for one explicitly supplied file, with no upload or remote lookup
• Manual Windows Wi-Fi MAC privacy controls with private-address validation and exact prior-override restoration

---

Platform support

Platform	Status	Notes
Windows 10/11 x64	Full support	Broad engine catalog, GUI, system proxy integration, split-tunnel proxy bypass patterns, DLL runtimes, and Windows-native VPN paths
Linux x86_64	Partial support	Supported paths: xray, tun, hysteria2, tuic through the managed blackout-engine runner
macOS	Not supported	No current runtime path
ARM devices	Not supported	Current binaries and runtime assumptions target x64 / x86_64 only

Linux scope in plain language

Linux does not support the Windows SNI injection path, GoodbyeDPI, Windows VPN engines, the desktop GUI, or Windows system-proxy bypass rules.

Linux currently supports:

• blackout connect xray
• blackout connect tun
• blackout connect hysteria2
• blackout connect tuic
• Linux endpoint-scoped kill switch
• Linux-targeted crash cleanup for Blackout-owned state

---

Engine map

Windows engine catalog

Engine	Category	Runtime path	Exposes local proxy?	Notes
sni	DPI bypass stack	blackout_core.dll	Yes	Uses the native SNI component plus XRay listeners
xray	Proxy core	blackout_core.dll	Yes	Supports VLESS, Trojan, VMess on Windows; REALITY is client-side VLESS support
gdpi	TCP handling	goodbyedpi.exe or experimental native DLL path	No	legacy is the stable default; native is experimental
psiphon	VPN/proxy client	blackout_warp.dll	Yes	Current runtime is DLL-backed
warp	VPN/proxy client	blackout_warp.dll	Yes	Current runtime is DLL-backed
tun	System tunnel	blackout_core.dll	No	Windows TUN requires admin rights
tor	Proxy client	tor.exe	Yes	Uses a user-supplied Tor runtime
mhrv	HTTP relay	blackout_core.dll	Yes	Embedded HTTP relay; HTTPS CONNECT is intentionally unsupported
ikev2	Windows native VPN	Windows RAS	No	Uses saved built-in VPN settings
wireguard	VPN	Windows runtime path	No	Requires a supplied .conf file
openvpn	VPN	Windows runtime path	No	Requires a supplied .ovpn file
softether	VPN	Windows runtime path	No	Requires installed SoftEther client components
appsscript	HTTP relay	Python engine	Yes	HTTP relay only
hysteria2	QUIC proxy	blackout_core.dll	Yes	Runs through the native sing-box-backed proxy engine
tuic	QUIC proxy	blackout_core.dll	Yes	Runs through the native sing-box-backed proxy engine
legend	Composite stack / security-oriented connect target	Tor + SNI + XRay stack	Yes	This is a connect/start target, separate from the legend security mode name

Linux engine catalog

Engine	Supported on Linux?	Runtime path	Notes
xray	Yes	blackout-engine	Requires a direct supported upstream config
tun	Yes	blackout-engine	Requires root and Linux networking prerequisites
hysteria2	Yes	blackout-engine	Uses sing-box proxy mode through the runner
tuic	Yes	blackout-engine	Uses sing-box proxy mode through the runner
sni, gdpi, psiphon, warp, legend, Windows VPN engines	No	—	Windows-only or otherwise unsupported on Linux

Important nuance: legend means two related but different things

Blackout Kit currently uses legend in two places:

• Security mode: blackout mode legend
• Composite start/connect target: blackout connect legend or blackout start legend

The security mode changes local XRay and legacy-GDPI policy. The engine target starts a Tor + SNI + XRay stack. The names overlap, but the behaviors are not identical.

---

Installation

Option 1 — standalone Windows executable

Download blackout.exe from the GitHub Releases page.

This is the easiest path for Windows users who want the packaged app.

Notes:

• first launch can extract packaged runtime assets into ~/.blackout-kit/
• the packaged executable still relies on local runtime files after extraction
• Windows admin prompts can still appear for engines or actions that require elevation

Option 2 — source or package install for contributors and advanced users

The installable core keeps GUI, packet capture, media, and torrent dependencies optional:

 git clone https://github.com/kiacoder/blackout-kit.git
 cd blackout-kit
 python -m pip install .
 blackout version

Feature extras are available when needed:

python -m pip install .[gui]
python -m pip install .[capture]
python -m pip install .[media]
python -m pip install .[torrent]
python -m pip install .[all]

The torrent extra uses the maintained libtorrent package on Linux Python 3.10–3.13 and is skipped on Windows and newer unsupported Python versions. Torrent commands report an actionable unavailable-feature message when the binding is unavailable. For contributor, test, and PyInstaller work, requirements.txt remains the portable all-feature development environment.

Then install the runtimes you actually need:

python blackout.py bins
python blackout.py bins download

Linux source/runtime install

Linux requires the blackout-engine runtime asset in bins/. Install the core package first; add [capture] only when packet capture is needed.

python3 -m pip install .

The core install does not pull in the Windows GUI, Scapy capture support, yt-dlp, or libtorrent.

Linux requires the blackout-engine runtime asset in bins/.

python3 -m pip install -r requirements.txt
mkdir -p bins
chmod +x bins/blackout-engine
python3 blackout.py version

The Linux runtime asset is produced by the repo CI and release pipeline as blackout-engine-linux-amd64, then used locally as bins/blackout-engine.

Runtime asset notes

Current runtime expectations from code:

• blackout_core.dll powers native Windows SNI, XRay, mhrv, TUN, and the experimental native GDPI path
• blackout_warp.dll powers current Windows WARP and Psiphon runtime paths
• blackout-engine powers the Linux managed runtime paths
• some Windows paths still rely on external user-supplied or downloaded binaries such as goodbyedpi.exe, tor.exe, openvpn.exe, and WireGuard/OpenVPN/SoftEther-related runtime pieces

Minimum requirements

Windows

• Python 3.10+ for source installs
• Windows 10 or 11 x64
• administrator approval for engines or actions that require elevation

Linux x86_64

• Python 3.10+
• iproute2
• either nftables or both iptables and ip6tables
• sudo for system tunnel, firewall, and repair actions
• bins/blackout-engine present and executable

---

Quick start

Golden path for Windows and Linux

Start with a safe overview, then let the local checklist identify what is needed:

blackout demo
blackout doctor --local-only
blackout capabilities
blackout route
blackout setup
blackout ready <engine>
blackout connect
blackout status

blackout setup is the beginner-friendly keyboard workflow. It can offer config editing, settings review, and a download of only the selected engine's missing runtime; each write, download, and connection remains explicit. blackout setup is read-only in JSON, quiet, and other non-interactive modes. Use blackout setup --connect only from an interactive terminal, after reviewing the final plan.

What the local states mean

blackout capabilities keeps the complete public engine catalog visible. Each engine is reported as ready, blocked, or unsupported for the current local platform:

• ready — local prerequisites passed; upstream reachability is still unknown.
• blocked — a local runtime, setting, permission, port, or saved config is missing.
• unsupported — this platform has no shipped runtime path for that target.

The catalog is intentionally broader than any one platform's runtime subset.

Linux direct path

Linux users should supply the managed runtime and a compatible direct upstream configuration before running the final steps:

python3 blackout.py setup
python3 blackout.py ready xray
sudo python3 blackout.py connect tun --background

---

Zero-argument launcher

Running blackout with no arguments opens a keyboard-navigable terminal chooser instead of doing anything automatically:

Blackout Kit — Choose How to Launch
> 💻 Terminal CLI   Navigate Blackout Kit entirely from this terminal
  🪟 Windows App    Open the desktop launcher window
  ❌ Exit           Quit Blackout Kit

↑↓ Move    →/Space/Enter Select    ←/Esc Back    Ctrl+C Quit

• ↑ / ↓ move the selection; Space, Enter, or → activate it; ← or Esc go back to the previous screen; Ctrl+C quits immediately.
• Terminal CLI opens the same arrow-key-navigable action menu (Connect, Engine, Status, Tools, Settings, …); backing out of it returns here instead of exiting.
• Windows App opens the CustomTkinter desktop GUI described in Desktop GUI; closing that window also returns here.
• The control legend is always shown at the bottom of every menu screen.
• Windows App is only offered on Windows, since the desktop GUI is Windows-only.

---

Command map

Core connection flow

blackout connect
blackout connect <engine>
blackout connect --background
blackout connect --iran
blackout connect --russia
blackout start <engine>
blackout start <engine> --russia
blackout emergency
blackout stop
blackout disconnect
blackout status
blackout status --watch
blackout demo
blackout capabilities [engine]
blackout route
blackout ready [engine]
blackout setup
blackout setup --connect

Config and settings

blackout config                  # keyboard config manager
blackout config edit             # keyboard config manager
blackout config list
blackout config validate
blackout config check-duplicates
blackout config compatibility
blackout config diff <setup>
blackout config add <uri>
blackout config replace <n> <uri>
blackout config import <url>
blackout config remove <n>
blackout config encrypt
blackout config decrypt
blackout config export --output setup.txt --force
blackout config import-setup <string> --force
blackout config profile-export --output profile.bkpf --stdin
blackout config profile-import profile.bkpf --stdin --force

blackout settings                # keyboard settings editor
blackout settings edit           # keyboard settings editor
blackout settings list
blackout settings get <key>
blackout settings set <key> <value>
blackout settings reset

The bare settings and config commands open keyboard-only editors in an interactive terminal. Use ↑/↓ to move, Enter, Space, or → to select, and ←/Esc to go back. Long lists show a bounded viewport that follows the selected row; mouse-wheel and mouse clicks are not used for selection. Setting edits are validated and saved immediately through the same settings API as the explicit commands. Config replacement asks for a new URI without displaying the old URI, so credentials are not exposed in the menu.

Plain setup exports contain credential-bearing URIs and require confirmation (or --force in automation). Portable profiles are authenticated and encrypted with a passphrase; use --prompt or --stdin so passphrases are never command-line arguments. Machine-readable output uses a versioned envelope, and supported read-only commands can be queried with --json.

Core and optional commands

The core package includes the CLI, local status/readiness, settings, config management, and local diagnostics. Install feature extras only when needed:

Extra	Enables
gui	Windows desktop app and tray dependencies
capture	Scapy packet capture; Windows also requires Npcap and Linux requires libpcap
media	yt-dlp media queue execution
torrent	libtorrent queue execution on supported Linux Python versions
all	All optional Python features

Missing optional features return an actionable installation error instead of a traceback. blackout doctor is core-only by default; add --include-optional to inspect packet-capture prerequisites.

Runtime trust and provenance

Automatic release downloads are staged and accepted only from approved HTTPS GitHub release hosts when release metadata includes a matching SHA-256 digest. Downloaded outputs are structurally checked before promotion, and verified output hashes are recorded in bins/.provenance.json; use the local integrity checks to detect later tampering. Existing binaries remain in place when verification fails.

Some cataloged engines still require a user-supplied or manual runtime. Those paths remain visible in the catalog, but are labeled manual/unverified rather than being presented as automatically authenticated downloads. Never paste credentials or raw proxy URIs into routine machine-readable output.

Proxy ownership

When Blackout Kit changes a local proxy, it records the exact target it owns. Cleanup restores or clears that state only while the current proxy still matches the recorded Blackout target. If another process changed the proxy afterward, Blackout Kit leaves that current state untouched.

Machine-readable output and completion

Use --json for supported structured commands:

blackout --json version
blackout --json status
blackout --json config validate
blackout --json settings list

Each success or error is one compact JSON object with schema_version, ok, and either data or error. Secrets, raw proxy URIs, and credentials are omitted. Unsupported delegated commands reject --json before running. Streaming/watch output uses one JSON object per line.

Typer shell completion is built in:

blackout --install-completion
blackout --show-completion

The optional local startup benchmark measures fresh subprocess startup only and performs no network or system changes:

python scripts/benchmark_startup.py --json

To include packet-capture checks in diagnostics:

blackout doctor --include-optional

No network probe is implied by the core-only local checks.

Diagnostics and recovery

blackout doctor
blackout doctor --fix
blackout doctor --fix-av
blackout fix
blackout fix --preview
blackout fix --history
blackout fix --full-route-reset
blackout fix --full-stack-reset
blackout fix --flush-arp
blackout tools netfix
blackout tools netfix --preview
blackout tools arp-flush

Network and helper tools

blackout scan
blackout tools ping [host]
blackout tools speedtest
blackout tools dns-bench
blackout tools dns-set <server>
blackout tools dns-flush
blackout tools traceroute [host]
blackout tools scan-file <path>
blackout tools file-hash <path>
blackout tools mac status
blackout tools mac randomize [--adapter <name>] [--force]
blackout tools mac restore [--adapter <name>] [--force]
blackout tools cert-check <host[:port]>
blackout tools cert-check <host> --allow
blackout tools hotspot
blackout tools share-vpn
blackout network
blackout network scan
blackout network isp
blackout network auto
blackout network switch <ssid>

Binary and runtime management

blackout bins
blackout bins download
blackout bins download <key>
blackout bins update
blackout update
blackout update --apply

Other surfaces

blackout gui
blackout mcp
blackout help
blackout help <topic>
blackout country
blackout country set <code>
blackout country reset
blackout split-tunnel list
blackout split-tunnel add <pattern>
blackout split-tunnel remove <pattern>

---

Security, privacy, and safety boundaries

Blackout Kit intentionally documents its limits.

Country and transport presets such as --iran and --russia are temporary local override bundles. They change runtime behavior for that launch only and do not rewrite your saved settings.

What it does provide

• local process/runtime orchestration
• local route and readiness guidance
• local encrypted storage for saved proxy URIs and supported VPN secrets
• Linux endpoint-scoped firewall protection when enabled and valid
• targeted cleanup of Blackout-owned network state after a crash
• Windows Defender-only scanning of one explicitly supplied local file without remediation
• local SHA-256 fingerprinting of one explicitly supplied file, with no upload or remote lookup

What it does not guarantee

• anonymity
• traffic-analysis resistance
• that a country profile will work on a given network
• that an upstream server is trustworthy
• that a local readiness pass means a tunnel will connect
• that a clean local port equals real internet reachability

Security modes in plain language

• speed — compatibility-focused local XRay and legacy-GDPI settings
• private — randomized XRay fingerprint plus MUX
• legend — stricter handling for known-bad normal TLS certificates

REALITY is handled separately by XRay’s configured REALITY handshake and does not use the normal TLS certificate policy.

File scan scope

blackout tools scan-file <path> scans exactly one existing regular file with the already-installed Windows Defender command-line scanner. It does not scan directories, download signatures, install or update a scanner, alter Defender exclusions, or change firewall, proxy, DNS, routing, or other security settings. Scans use Defender's non-remediating mode; a nonzero result is reported as a detection only when Defender's captured output independently confirms one.

File hash scope

blackout tools file-hash <path> calculates a SHA-256 fingerprint for one existing regular file locally. It streams the file in bounded chunks and refuses to present a digest when its before/after file snapshot changes during reading. It does not upload the file or its hash, contact VirusTotal or any other service, use an API key, scan for malware, or alter security or network settings.

Wi-Fi MAC privacy scope

blackout tools mac status only inspects the currently active physical Wi-Fi adapter. randomize and restore are Windows-only, explicit actions that ask for confirmation before briefly restarting that one adapter; non-interactive use requires --force. Fresh addresses and optional custom addresses must be locally administered and unicast. Before Blackout Kit's first change, it saves the adapter's prior NetworkAddress driver override and restore reinstates that exact override—or removes it to return to the hardware default when no override existed. This feature never changes a MAC automatically and does not change firewall, DNS, proxy, routes, VPNs, or other adapters. Some Wi-Fi drivers do not support a software MAC override.

Kill switch scope

• Linux: supported, endpoint-scoped, Blackout-owned firewall tables/rules only
• Windows: unsupported; legacy Windows rules are removed because Windows Firewall block rules override the per-process allow rules they would need

Recovery scope

Default recovery is intentionally narrow. It does not behave like “reset everything” unless the user explicitly asks for the broader Windows-only reset flags.

For deeper details, read SECURITY.md.

---

Data and local state

Blackout Kit stores sensitive local operational state. Depending on what features are used, this can include:

• settings in ~/.blackout-kit/settings.json
• encrypted or plaintext proxy configuration storage
• encrypted or plaintext supported VPN secrets
• daemon logs
• recovery audit history
• system-proxy bypass patterns
• stability history and local event state
• engine-specific runtime caches created by local components

Important boundaries:

• routine terminal and MCP settings reads mask supported VPN secret fields
• encrypted storage is machine-bound, not portable
• blackout config decrypt is a same-machine recovery action that restores plaintext files
• upstream proxy or VPN operators can still observe traffic that passes through their servers

---

MCP server

Blackout Kit includes a stdio MCP server:

{
  "mcpServers": {
    "blackout-kit": {
      "command": "blackout",
      "args": ["mcp"]
    }
  }
}

Current tool surface includes:

• blackout_ready
• blackout_connect
• blackout_disconnect
• blackout_emergency
• blackout_status
• blackout_read_logs
• blackout_config
• blackout_settings
• blackout_split_tunnel
• blackout_net_tools
• blackout_scan
• blackout_doctor
• blackout_security_mode

Important MCP boundaries:

• the MCP server is not a general-purpose network scanner
• connect requires an explicit engine choice
• the MCP layer does not expose the Iran profile toggle
• blackout_doctor is currently read-only from MCP and does not forward a fix action
• some MCP calls can still modify local networking or saved state

---

Desktop GUI

The Windows GUI is started with:

blackout gui

It is built with CustomTkinter and currently serves as a native desktop surface for the same general runtime, monitoring, and settings workflows.

Running blackout with no arguments always opens the terminal chooser first (see Zero-argument launcher); picking Windows App from that chooser is what opens this GUI window.

---

Split tunnel

blackout split-tunnel manages Windows system-proxy bypass patterns.

It does not implement per-process routing, packet-level route tables, or Linux tunnel rules.

Example:

blackout split-tunnel add example.com
blackout split-tunnel add 192.168.1.*
blackout split-tunnel list

On Windows these rules map to ProxyOverride behavior for the system proxy path.

---

Troubleshooting

A connection command fails immediately

blackout doctor
blackout ready <engine>
blackout route

The system is left offline or broken after a crash

blackout stop
blackout fix

Use the broader Windows-only flags only if targeted recovery fails.

A binary is missing

blackout bins
blackout bins download

Linux tun will not start

Check:

• sudo / root privileges
• bins/blackout-engine
• iproute2
• firewall backend availability
• a direct compatible saved upstream config

LEGEND mode refuses a normal TLS host

blackout tools cert-check example.com
blackout tools cert-check example.com --allow

This does not apply to REALITY.

YouTube pages load but videos fail under GoodbyeDPI

GoodbyeDPI is TCP-oriented. Browser video playback can prefer QUIC/UDP, which bypasses that path.

See the user guide’s troubleshooting section for the browser-side QUIC explanation and workaround.

---

Roadmap and contributing

• Product direction and future work: ROADMAP.md
• Security posture and disclosure: SECURITY.md
• End-user setup and workflows: docs/user-guide.md
• Contributor and maintainer workflows: CONTRIBUTING.md

---

License

MIT — see LICENSE.

---

Disclaimer

Blackout Kit is intended for legitimate personal use such as accessing blocked educational resources, development tools, personal communications, and ordinary web services.

Users are responsible for their own legal and operational decisions. The author and contributors do not guarantee that any engine, profile, mode, or upstream service will be safe or effective in a given environment.

---

Made by Kiacoder — for people who just want a working internet connection.