starhub-kit
Compiles Linux nftables/iptables firewall policies for AI sandbox isolation, including dual-stack allowlists and hard-drops for SSH, Postgres, and Redis access.
Compiles macOS Packet Filter (pf) policies for AI sandbox firewalls, restricting access to local services and RFC 1918 LAN ranges.
Generates official Tailscale ACL JSON and 100.x/4via6 mesh routing policies to isolate AI agents and avoid RFC 1918 subnet collisions.
StarHub Kit (starhub-kit)
Language: English | 简体中文 (Simplified Chinese)
Version:v1.3.0· Runtime: Python 3.9+ (Zero Third-Party Dependencies) · MCP:starhub mcp(stdio) · Nix:flake.nix· Assurance: OpenSSF Silver (#16658) + OSPS Baseline L3
StarHub Kit is a zero-dependency AI Agent sandbox firewall & cross-platform network policy compiler for Linux nftables/iptables, macOS Packet Filter (pf), official Tailscale ACL JSON, Sing-box / Mihomo split-DNS & surgical QUIC (UDP/443) governance, and multi-site 100.x + 4via6 mesh routing — with a built-in Model Context Protocol (MCP) server.
Prevent autonomous coding agents (Claude Code, Codex, OpenHands, Cursor, Docker MCP containers) from scanning your RFC 1918 LAN or reaching :22 SSH / :5432 Postgres / :6379 Redis, eliminate hotel Wi-Fi subnet collisions, and cure mobile QUIC blackholes from one declarative JSON topology (STARHUB_GROUND_TRUTH.json).
Try in 10 Seconds (Zero Root, Zero Disk Writes)
# Option A — One-command install via official Homebrew tap (macOS & Linuxbrew)
brew install Ziqi/tap/starhub-kit
starhub render --profile ai-sandbox --target tailscale-acl --dry-run
starhub render --profile ai-sandbox --target macos-pf --dry-run
starhub render --profile ai-sandbox --target nftables --dry-run
# Option B — Preview Sing-box or Mihomo split-DNS & surgical QUIC rulesets directly to stdout
git clone https://github.com/Ziqi/starhub-kit.git && cd starhub-kit
./bin/starhub render --target singbox --dry-run
./bin/starhub render --profile minimal --only mihomo --dry-run
# Option C — Mount directly in Claude Desktop / Cursor / Windsurf as a zero-dependency MCP Server
# Add to mcpServers: { "starhub": { "command": "starhub", "args": ["mcp"] } }
nix run github:Ziqi/starhub-kit -- audit --profile ai-sandboxWhy StarHub Kit? (4 Real-World Infrastructure Pain Points Solved)
Pain Point in Typical Homelab / Multi-Site Setups | StarHub Declarative Engineering Architecture |
1. Hotel / Coffee-Shop Wi-Fi Subnet CollisionsAdvertising raw | Zero-Collision Native |
2. Cross-Border Proxy Stalls & QUIC BlackholesBlind DNS | Deterministic Split-DNS + Top-Ordered ( |
3. Cloud AI Agent Split-Brain & Lateral Movement RiskMultiple cloud AI sandboxes sharing a Tailscale state file collide on | Restricted Cloud Sandbox Guest Pass ( |
4. Documentation Sprawl, Drift & Accidental PII / Inventory LeaksDozens of stale | Unified Governance ( |
Related MCP server: claude-mac-bridge
Architecture Overview
flowchart LR
subgraph Controllers["Controllers & Cloud Sandboxes"]
LAP["Primary Controller (laptop)<br/>127.0.0.1:17890 Adaptive Tunnel"]
WS["Compute Workstation (workstation)<br/>Dedicated VPS2 + Host Firewall Isolation"]
BOT["Cloud AI Agent Pool (B2)<br/>Isolated /tmp/tailscale-id"]
end
subgraph Core["Site-A Core Cluster (Proxmox VE)"]
GW["gw (LXC 100 · .11 + .12 VIP)<br/>Mihomo gvisor TUN + Split-DNS<br/>Cam-Gate + IPv6 Exit Guard"]
PAN["panel (LXC 102 · .15:3001)<br/>16 Probes + Zero-Drift Doctor<br/>STARHUB-DASH-ACL + BOT-NOSSH"]
HOM["home (LXC 103 · .20:8080)<br/>Smart Home & AI Hub<br/>STARHUB-HOME-ACL + BOT-NOSSH"]
end
subgraph Relay["Out-of-Band Bastion & Egress"]
DERP["Custom DERP + Lifeline Bastion<br/>:8443 + STUN :3478 + 127.0.0.1:2201..2204"]
VPS["VLESS-Reality Egress Fleet<br/>VPS1 / VPS2 / VPS3 (bbr + fq)"]
end
LAP & WS -->|"Native 100.x / Dual-Stack Allowlist"| GW & PAN & HOM
BOT -->|"HTTP :3001/:8080 ONLY (:22 Hard DROP)"| PAN & HOM
GW & WS -->|"Anti-Loop Direct Exemption"| VPS
GW & WS -.->|"Reverse SSH Lifeline (:2203/:2204)"| DERPChoose Your Adoption Tier (30 Seconds to Full Blueprint)
You do not need Proxmox VE, dedicated observability hosts, or three overseas relays to benefit from StarHub Kit. Choose the tier or modular slice (--only mihomo|firewall|ai-sandbox|lifeline) that fits your setup (see docs/ARCHITECTURE-AND-PLAYBOOK-EN.md):
Tier | Hardware Needed | Setup Time | How to Use |
Tier AI · Autonomous Agent Firewall ( | Any Mac / Linux workstation or Tailscale tailnet running Claude Code, Codex, OpenHands, or Docker AI containers | 15 seconds |
|
Tier 0 · Drop-In Ruleset ( | Any existing Sing-box / OpenWrt / Clash Verge / Mihomo Party / Stash + Tailscale setup | 30 seconds | Run |
Tier 1 · StarHub Lite ( | 1 Gateway + 1 Laptop/PC + 1 Egress (no PVE, no custom DERP, no extra VMs) | 3 minutes | Edit 3 items in |
Tier 2 · Full Blueprint ( | Multi-site mesh + isolated compute workstation + cloud AI sandboxes + IoT camera kill-switch | 15 minutes |
|
3-Minute Full Workflow
# 1. Initialize STARHUB_GROUND_TRUTH.json (full or --profile minimal)
./bin/starhub init
# 2. Preview individual subsystems to stdout (zero disk writes) or export a deployment bundle
./bin/starhub render --only firewall --dry-run
./bin/starhub render --out-dir ./dist
# 3. Run the 7-dimension static harness, bit-for-bit reproducible archive gate & 2,000-iteration fuzz suite
./bin/starhub render --check
./bin/starhub archive --verify
./bin/starhub doctor --local-docs-only
python3 ./tests/fuzz_starhub_ctl.py --iterations 2000
# 4. Install the Git pre-commit guardrail
cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commitRepository Structure (1 Core + 6 Books + 2 Ledgers)
Path | Description |
STARHUB_GROUND_TRUTH.json / topology.example.json / profiles/topology.minimal.json | Single Source of Truth (SSOT): role-based declarative node inventory, dual-stack allowlists, egress definitions, IoT guardrails, and Markdown whitelist |
| Declarative Compiler & Reproducible Builder: modular |
| Verification Harness: 8-dimension drift detector + |
AGENTS.md ( | Unified AI & Operator Entrypoint: Ten Iron Guardrails and zero-hallucination workflow |
The 6 Golden Books: Architecture, Daily Ops & Security Matrix, Troubleshooting & 1-Hour Bare-Metal DR, Audit Index, Smart Home Hub, and Multi-Agent Playbook | |
StarHub v2.0 Plugin Specification: declarative | |
Dual Ledgers: append-only |
Dual-Repo Private/Public Workflow (Zero-PII & Zero-Inventory Sanitizer)
If you run a private production repository alongside a public fork of starhub-kit, verify mathematically before every public release that zero private IPs, Tailscale addresses, MACs, domains, handles, or private device/vendor identifiers exist anywhere in the public working tree or .git commit history:
python3 scripts/starhub-doctor.py \
--verify-public-export /path/to/starhub-kit \
--private-gt /path/to/private/STARHUB_GROUND_TRUTH.jsonSecurity, OSPS Baseline L3 & Supply-Chain Assurance
Every release and main build publishes a Sigstore + GitHub OIDC SLSA Build Level 3 provenance certificate, an ISO/IEC 5962 (SPDX-2.3) SBOM, a bit-for-bit reproducible source archive (mtime=0, uid/gid=0), and an offline Ed25519 signature, audited under OpenSSF Best Practices Silver (#16658) and aligned with OpenSSF OSPS Baseline (Level 3):
# 1. Verify GitHub OIDC / Sigstore SLSA Build Level 3 provenance certificate
gh attestation verify starhub-kit-v1.3.0.tar.gz --repo Ziqi/starhub-kit
# 2. Verify bit-for-bit reproducible tarball against source tag
./bin/starhub archive --verify-file ./starhub-kit-v1.3.0.tar.gz --prefix starhub-kit-v1.3.0Released under the MIT License. Please review GOVERNANCE.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md before submitting a pull request.
Available Tools
3 toolsaudit_topology_securityC
Audit a StarHub topology JSON for RFC 1918 Wi-Fi subnet collisions and exposed AI sandbox SSH/database ports.
Inputs: topology_json.
compile_ai_sandbox_policyC
Compile zero-lateral-movement firewall / ACL policy for autonomous AI coding agents (Linux nftables, macOS pf, Tailscale ACL JSON, or Linux iptables).
Inputs: backend, sandbox_ips, allowed_api_targets.
render_quic_mesh_guardrailsC
Render deterministic Tailscale split-DNS + surgical Apple/Gmail UDP/443 QUIC ruleset for Sing-box or Mihomo (Clash Meta).
Inputs: engine.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct action and target: rendering QUIC/mesh guardrails, auditing topology security, and compiling AI sandbox policy. There is little risk of confusing one tool for another despite the shared networking/security domain.
All tool names use consistent snake_case with a leading verb and descriptive noun phrase. The pattern is predictable across render_, audit_, and compile_.
Three tools is well-scoped for a specialized network/security policy kit, with each tool covering a distinct workflow. No tool appears redundant or out of place.
The surface covers rendering guardrails, auditing topology, and compiling sandbox policy, which are the core operations implied by the kit. Minor gaps exist around validating generated outputs or applying policies, but agents can work around these.
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
Related MCP Servers
- AlicenseAqualityBmaintenanceA local-first MCP server that gives AI coding agents persistent memory and controlled commands. Features a git-backed markdown knowledge vault with FTS5 search, surgical section edits, token-aware context budgeting, and a sandboxed command engine with human approval gates. Works with Claude Code, Cursor, Copilot, Gemini, and more.62601 npm1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server that lets an AI agent delegate tasks to Claude Code on a remote Mac via SSH over Tailscale. Persistent sessions, 200k context, full Mac filesystem access.MIT
- AlicenseNot gradedqualityBmaintenanceA macOS-native MCP server that provides AI hosts with fresh workspace state, bounded context, and retained execution evidence, avoiding collapsing operations into shell strings.23 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceA local-first MCP server that enables AI-assisted coding through workspace-scoped tools for file reading/editing, command execution, jobs, Git, LSP, media, browser, and desktop workflows. It enforces OAuth, workspace ACL, trust policies, and file/secret guards so owners can safely grant inspect, edit, or trusted capabilities.559 npmMIT