Skip to content
BranchesTags

Repository files navigation

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

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

Python Platform GUI License Version Security Audited Status

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

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:

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

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

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 install for contributors and advanced users

 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 source/runtime install

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

Fast path for Windows users

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

Fast path for Linux users

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

Suggested first-run order

  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

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

Config and settings

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

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

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.

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.

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

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

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.

About

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

kiacoder.github.io/blackout-kit/

Topics

anti-censorshipauto-detectcensorship-circumventionchinaclicountry-profiledpi-bypassing-wingoodbyedpihysteria2iranlinuxproxypsiphonpythonrussiatuictunwarpwindowsxray

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages