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

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

Blackout Kit Desktop is a separate Windows WPF/C# product in early prototype. Its current milestone is a read-only named-pipe snapshot view; it is not CLI parity and cannot connect/stop engines yet. See desktop/README.md and desktop/CAPABILITY_COVERAGE.md.

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.

⚡ New in 1.9.0 — AmneziaWG, native

Obfuscated WireGuard with real junk-packet parameters (Jc/Jmin/Jmax, S1–S4, H1–H4), running entirely in userspace. No TUN device. No drivers. No admin rights. No sing-box patchset.

Verified against a live production server, not a lab: handshake registered ✅ · 1.5 MB transferred ✅ · curl through the tunnel returns the server's IP ✅ · YouTube 200 through both the SOCKS5 and HTTP proxies ✅.

blackout settings set awg_config_file C://path//to//awg.conf
blackout start awg -d        # SOCKS5 :11080 · HTTP :11081 (system proxy)

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

---

Table of contents

• Security & Privilege Model
• What Blackout Kit is
• Verified, not promised
• 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

---

Verified, not promised

Every number below was measured on real hardware against real servers — not a lab mock.

Claim	Evidence
AmneziaWG handshake works	Production server: fresh latest-handshake, 1.5 MB transferred, 784 packets on awg0
Traffic really exits the server	curl -x http://127.0.0.1:11081 https://api.ipify.org → 185.215.244.95 (the server's own IP)
YouTube loads through the tunnel	https://youtube.com → 200 in 3.3 s, via HTTP proxy and SOCKS5 alike
Windows browsers work	System proxy is HTTP (WinINET cannot use SOCKS); Chrome needs no flags
No admin, no drivers	Userspace netstack; no elevation, no WinDivert, no TUN adapter
The test suite is green	1,523 passed, 2 skipped
The servers are hardened	SSH key-only, fail2ban (68 brute-force attempts blocked on day one), ufw default-deny

If a claim does not reproduce on your machine, that is a bug — open an issue with the output of blackout doctor.

---

Security & Privilege Model

Standard userspace proxying needs no administrator rights. Starting an engine that exposes a local SOCKS5 or HTTP proxy, and pointing the system proxy at it, runs from an ordinary user account:

• Zero admin or root. No elevation prompt and no sudo.
• No drivers. Nothing is installed into the kernel or added as a network adapter.
• No Defender exclusions. Connecting never adds one. An exclusion is only ever created when you run blackout config --setup-defender-exclusion and type yes.
• Per-user proxy setting. On Windows the system proxy is written under HKEY_CURRENT_USER.

Engines in this userspace group are xray, hysteria2, tuic, and appsscript. The code confirms that none of them appears in the elevation lists (ENGINES_REQUIRING_ADMIN and _WINDOWS_ELEVATED_ENGINES) and none loads the WinDivert driver.

# Unprivileged quick start: a local SOCKS5/HTTP proxy, no elevation
blackout config add --prompt             # paste the URI you already have (not echoed, not in shell history)
blackout connect xray                    # start the userspace XRay proxy

Elevated privileges are opt-in. Blackout asks Windows for elevation (UAC), or requires root on Linux, only when you start an engine or feature that needs it:

Capability	Engines or features	Why it needs elevation
Packet interception	gdpi (legacy GoodbyeDPI)	Captures and rewrites packets through the WinDivert driver. See WinDivert driver and Windows Defender
Virtual network interface	tun (Windows admin, Linux root), wireguard, openvpn, softether, ikev2	Creates a tunnel adapter and changes routes
Launcher elevation on Windows	warp	Blackout elevates this engine on Windows even though it serves a local proxy. That is a launcher policy, not a packet-level requirement
Firewall rules on Linux	kill_switch setting (off by default)	Programs firewall tables; the Linux kill switch runs only as root

Elevation is therefore not limited to packet-level engines and TUN. It also covers VPN adapter engines, the Windows warp launch policy, and the Linux kill switch. The userspace guarantee above holds only for the engines listed in its group.

Userspace does not mean private. A local proxy still sends traffic to whichever upstream you configure. See NETWORK_PRIVACY.md for every outbound connection and SECURITY.md for the full threat model.

---

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.8.0 currently includes:

• Typer-based public CLI with backward-compatible delegation into the proven command dispatcher
• Zero-flag launcher flow that always opens a keyboard-navigable terminal chooser (Terminal CLI / Windows App); the GUI opens only when explicitly selected
• Desktop GUI built with CustomTkinter
• MCP stdio server for AI clients with a constrained, documented tool surface
• Iranian ISP sub-profiles — blackout isp list, transient --profile ir-mci|ir-irancell|... carrier presets, an interactive carrier picker on bare blackout connect (with ASN auto-detect), a one-connection --sni-spoof <domain> flag, and blackout tune fragment which pairs a clean IP with a TLS fragmentation setting measured through real handshakes; all overrides ride the temporary mechanism and never rewrite saved settings
• v2 socks-tunnel engine — blackout start socks-tunnel supervises the Go blackout-core daemon over its local IPC channel and exposes a loopback SOCKS5 tunnel with fake-SNI rewrite and randomized SNI-boundary segmentation (v2_tunnel_port, default 18080). Build the daemon with go -C engine/v2 build -o bins/blackout-core.exe ./cmd/blackout-core or set BLACKOUT_CORE_BIN
• Operator observability layer — canonical blackout snapshot, deterministic blackout operator recommend with safety classes, sanitized blackout support-bundle, local event journal, and an opt-in loopback SSE event stream. Deterministic core logic, not an embedded AI model; external AI systems consume it via MCP
• 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
• Enterprise & Team (Roadmap Phase 7) — role-based access control (viewer/operator/admin), a distributable and optionally HMAC-signed access policy document, a multi-device registry with an online/offline dashboard, and GDPR/HIPAA/SOC 2 control checklists scored from the effective settings
• Developer ecosystem (Roadmap Phase 8) — a Python SDK (from blackoutkit.sdk import Blackout) that is a thin facade over the CLI internals, a plugin system for custom rules/analyzers/exporters, a community marketplace with SHA-256-verified installs, and a read-only REST API v2 with webhooks and a WebSocket event stream
• Self-heal and VM safety — blackout tools vmcheck reports VM detection and leftover state, the daemon heals its own leftovers at startup, and the Go core recovers from panics instead of killing the host process

---

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 and the WinTUN driver; the driver is never downloaded or installed automatically, and readiness does not claim the driver is loaded — sing-box startup is the final check
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

Verify the release (SHA-256)

Every release publishes checksums.txt (SHA-256 for each release asset) and blackout.exe.sha256. install.ps1 in the repository root downloads the latest blackout.exe, checks it against that checksum before anything is installed, and refuses to install if no checksum is published. Run it as a file: powershell -ExecutionPolicy Bypass -File .\install.ps1. A failed check exits non-zero, and piping the script into Invoke-Expression would end the shell that runs it.

To verify a manual download in PowerShell:

$base = "https://github.com/kiacoder/blackout-kit/releases/latest/download"
Invoke-WebRequest -UseBasicParsing -Uri "$base/blackout.exe" -OutFile blackout.exe
Invoke-WebRequest -UseBasicParsing -Uri "$base/checksums.txt" -OutFile checksums.txt
$line = Get-Content checksums.txt | Where-Object { $_ -match '\sblackout\.exe$' } | Select-Object -First 1
$expected = $line.Split(' ', [StringSplitOptions]::RemoveEmptyEntries)[0]
$actual = (Get-FileHash -Algorithm SHA256 .\blackout.exe).Hash
if ($actual.Trim() -ieq $expected.Trim()) { "OK: $actual" } else { "MISMATCH: expected $expected, got $actual" }

On Linux, or with GNU coreutils available:

curl -fLO https://github.com/kiacoder/blackout-kit/releases/latest/download/blackout-engine-linux-amd64
curl -fLO https://github.com/kiacoder/blackout-kit/releases/latest/download/checksums.txt
sha256sum --ignore-missing -c checksums.txt

The checksum comes from the same release as the file. It catches corrupted or substituted downloads, but on its own it cannot defend against a compromised release, which would change both files.

Verify build provenance (GitHub Sigstore)

Every release asset — blackout.exe, blackout-engine-linux-amd64, blackout-source.zip, checksums.txt, blackout.exe.sha256 — is covered by a signed SLSA build-provenance attestation produced by this repository's own Actions workflow (.github/workflows/build.yml, actions/attest-build-provenance@v2). Verify the file you downloaded against it:

# 1. Verify cryptographic provenance via GitHub Sigstore:
gh attestation verify blackout.exe --repo kiacoder/blackout-kit

# 2. Verify SHA-256 checksum. blackout.exe.sha256 holds "<hash>  blackout.exe", so take the first field:
$expected = ((Get-Content .\blackout.exe.sha256) -split '\s+')[0]
(Get-FileHash -Algorithm SHA256 .\blackout.exe).Hash -ieq $expected

Get-FileHash emits uppercase hex, while .sha256 and checksums.txt use lowercase. Compare with -ieq (or .ToLowerInvariant() on both sides). -ceq is case-sensitive and reports a false mismatch.

gh attestation verify blackout.exe --repo kiacoder/blackout-kit --format json | jq '.[0].verificationResult'
sha256sum -c checksums.txt

Provenance answers the question a digest cannot: it states which repository, commit, and workflow run produced these bytes, signed by a short-lived Sigstore certificate. Releases tagged before this change carry no attestation — for those, verify the checksum and compare it against an independent copy of checksums.txt. See SECURITY.md for the full assurance matrix.

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 --setup-defender-exclusion    # exclude only bins/windivert from Defender (asks you to type yes)
blackout config --remove-defender-exclusion   # undo that exclusion (asks you to type yes)
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 --fix never changes Windows Defender settings. Defender exclusions are added only through the confirmed commands listed in the config section.

blackout doctor
blackout doctor --fix
blackout doctor --fix-av           # same confirmed WinDivert-only exclusion as config --setup-defender-exclusion
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 vmcheck                # VM detection + leftover state + recovery steps
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>

# Enterprise & Team (Roadmap Phase 7)
blackout enterprise                          # org, principals, device summary
blackout enterprise roles
blackout enterprise policy
blackout enterprise assign <name> <role>     # viewer | operator | admin
blackout enterprise devices
blackout enterprise device-add <id> [--name <n>] [--platform <p>] [--status <s>]
blackout enterprise compliance [--framework gdpr|hipaa|soc2|all]

# Developer ecosystem (Roadmap Phase 8)
blackout tools plugins                       # list discovered plugins
blackout tools plugins run <name> --context '<json>'
blackout tools marketplace                   # installed plugins
blackout tools marketplace list
blackout tools marketplace search <query>
blackout tools marketplace refresh           # fetch catalog (explicit egress)
blackout tools marketplace install <name>    # SHA-256 verified
blackout tools marketplace remove <name>

blackout enterprise is local-first: the policy document is a distributable JSON file (optionally HMAC-signed), the device registry is a shared JSON file, and the compliance checks read the effective settings. Nothing is uploaded.

Embedding Blackout Kit from Python (the SDK):

from blackoutkit.sdk import Blackout

bk = Blackout()
bk.version                 # "1.8.0"
bk.engines()               # ['auto', 'xray', 'sni', ...]
bk.readiness("xray")       # {"engine", "ready", "checks"}
bk.metrics() / bk.connections(process="chrome", port=443) / bk.bandwidth()
bk.roles() / bk.policy() / bk.can("alice", "connect")   # Phase 7
bk.devices() / bk.compliance("gdpr")                    # Phase 7
bk.connect() / bk.status() / bk.disconnect()

The SDK is a thin facade over the same internals the CLI uses, so the two can never disagree; typed exceptions derive from BlackoutError. A read-only REST API v2 (blackout api start, then /api/v2/events, /api/v2/webhooks, /api/v2/plugins, /api/v2/devices, /api/v2/compliance, and a /api/v2/ws/events WebSocket stream) exposes the same data locally and is loopback-only by default.

---

## Operator: structured observability (Blackout Operator foundation)

Blackout Kit exposes clean structured state, events, and recommendations so
external AI systems (ZCode, GLM, Claude, ChatGPT, avatar hosts, or any MCP
client) can reason over it. The Operator layer is deterministic core logic —
**not an embedded AI model** — and nothing is ever uploaded.

```bash
blackout snapshot              # canonical local state (add --json for stable JSON)
blackout operator status       # live operator view (add --watch)
blackout operator recommend    # deterministic recommendations with safety classes
blackout operator actions      # documented action catalog
blackout events recent         # sanitized local event journal
blackout events serve          # OPTIONAL SSE stream, loopback-only (127.0.0.1:8787)
blackout support-bundle --preview   # inspect a bug-report bundle before export
blackout support-bundle             # write sanitized JSON locally; never uploaded

Boundaries that matter:

• snapshots, readiness, recommendations, and events describe local state; none of them prove upstream reachability or successful censorship bypass
• recommendations carry safety classes (READ_ONLY → DESTRUCTIVE); Blackout Kit never silently executes disruptive or broad repair because a client asked
• the event stream is off unless you run it, binds to loopback only, and has no control surface
• support bundles remove passwords, tokens, keys, PSKs, and proxy/VPN/SSH URIs entirely (no partial masking) and never read vault contents

See blackout help operator and SECURITY.md for the full data inventory.

---

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

WinDivert driver and Windows Defender

GoodbyeDPI uses WinDivert, a packet-capture driver. Windows Defender and other antivirus products often flag WinDivert and tools built on it. These detections are commonly false positives for this use, but Blackout cannot verify them, so it does not hide them.

• Isolated layout: the driver files (WinDivert.dll, WinDivert64.sys) live only in bins/windivert/. The GoodbyeDPI executable stays in bins/. Launches use bins/windivert/ as the working directory, so Windows loads the driver from there.
• Narrow exclusion only: the only folder Blackout will ask Defender to exclude is bins/windivert/. It refuses if the folder is not that path, is a symbolic link or junction, or contains anything other than the two driver files. It never excludes bins/, a parent folder, or an executable.
• Never automatic: blackout doctor --fix does not touch Defender. blackout config --setup-defender-exclusion (or doctor --fix-av) prints a warning, then requires you to type yes. Windows shows a UAC prompt only after that answer. Without an interactive terminal, nothing changes.
• Declining is safe: nothing changes, and you can keep using SOCKS5/HTTP modes such as blackout connect xray, which do not load WinDivert.
• Limits: an exclusion does not turn Defender off, and it does not cover other files in bins/. If Defender still flags goodbyedpi.exe, use a non-driver mode or review that detection yourself. Remove the exclusion with blackout config --remove-defender-exclusion, or manually with Remove-MpPreference -ExclusionPath "<path>".
• Older installs: earlier versions kept the driver in bins/ and may have excluded all of bins/. blackout doctor (run as administrator) reports that broad exclusion and shows how to remove it. Run blackout bins download goodbyedpi once to move the driver into bins/windivert/.

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. For the complete list of outbound connections Blackout Kit can make — none of them telemetry — read NETWORK_PRIVACY.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
• blackout_snapshot (canonical local state; never proves remote success)
• blackout_recommend (deterministic recommendations with safety classes)
• blackout_recent_events (sanitized local event journal)
• blackout_support_bundle_preview (bundle structure without content)

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
• privileged MCP calls that change local networking, DNS, hotspot, or saved state require the MCP authorization token described below

MCP authorization

Privileged MCP tools change settings, the daemon, DNS, hotspot, or network state. They run only when the server has a secret and the caller presents it:

• Set BLACKOUT_MCP_TOKEN (or BLACKOUT_MCP_SECRET, used when the first is unset) in the environment of the MCP client that launches blackout mcp. The server reads it at call time.
• Pass the same value as the auth_token argument of every privileged call.
• The server compares the two values with hmac.compare_digest. If no secret is configured, privileged calls are denied. The check fails closed, and a denied call comes back as a failed result (isError) rather than text an agent could misread as success.

Client configuration with a token:

{
  "mcpServers": {
    "blackout-kit": {
      "command": "blackout",
      "args": ["mcp"],
      "env": { "BLACKOUT_MCP_TOKEN": "<long random value>" }
    }
  }
}

Generate a value with python -c "import secrets; print(secrets.token_urlsafe(32))". The agent must receive the token to call privileged tools, so treat it like a password: anything that can read that agent's context can read it. Rotate it by changing the client's env value and restarting the client. The server never echoes the token and never logs it.

Privileged calls (token required):

• blackout_connect and blackout_emergency (including the tun engine, which creates a TUN interface)
• blackout_disconnect
• blackout_config with add, import, or remove
• blackout_settings with set or reset
• blackout_split_tunnel with add or remove
• blackout_security_mode with a mode
• blackout_net_tools with dns-set, dns-flush (DNS changes), hotspot (hotspot control), or netfix (network recovery)

Read-only calls need no token: blackout_ready, blackout_status, blackout_read_logs, blackout_doctor, blackout_scan, blackout_snapshot, blackout_recommend, blackout_recent_events, blackout_support_bundle_preview, list and get actions of config, settings, and split tunnel, blackout_security_mode without a mode, and blackout_net_tools with ping, dns-bench, netfix-preview, or netfix-history.

---

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
• Exactly which network contacts exist and when: NETWORK_PRIVACY.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.