kiacoder/blackout-kit: Network toolkit with 17+ engines, MCP server for AI integration, smart config rotation, data-phase drop detection, and country-aware routing. Terminal-first. Windows + Linux · GitHub

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

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

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.

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.

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

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

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.

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

 git clone https://github.com/kiacoder/blackout-kit.git
 cd blackout-kit
 pip install -r requirements.txt
 python blackout.py version

Then install the runtimes you actually need:

python blackout.py bins
python blackout.py bins download

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.

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

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

python blackout.py doctor
python blackout.py bins download
python blackout.py route
python blackout.py connect

python3 blackout.py doctor
python3 blackout.py route
sudo python3 blackout.py connect tun --background

1. blackout doctor — inspect local prerequisites
2. blackout bins / blackout bins download — install downloadable runtimes
3. blackout config add ... or blackout config import ... — add upstream configuration if needed
4. blackout route — see locally ready candidates
5. blackout ready <engine> — validate a selected engine locally
6. blackout connect — connect using the local recommendation
7. blackout status — inspect daemon/proxy/local-port state

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 route
blackout ready [engine]

blackout config list
blackout config add <uri>
blackout config import <url>
blackout config remove <n>
blackout config encrypt
blackout config decrypt

blackout settings list
blackout settings get <key>
blackout settings set <key> <value>
blackout settings reset

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

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 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>

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

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>

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.

• 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

• 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

• 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.

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.

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.

• 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

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.

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

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

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.

The zero-argument launcher path can also open the GUI first and fall back to the terminal menu when GUI dependencies are unavailable.

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.

blackout doctor
blackout ready <engine>
blackout route

blackout stop
blackout fix

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

blackout bins
blackout bins download

Check:

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

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

This does not apply to REALITY.

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.

• 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

MIT — see LICENSE.

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.