Ackwrap

A local-first control plane for sing-box.
Turn subscriptions, nodes, policies, DNS, and routes into a validated runtime configuration.

Download · Features · How it works · Development · 简体中文

_{Core control, policy modes, health checks, traffic, and maintenance in one dashboard.}

Why Ackwrap

sing-box is powerful, but a production-sized JSON configuration is not pleasant to operate by hand. Ackwrap puts the full configuration lifecycle behind one focused web console:

One node pipeline	Parse remote subscriptions and local imports, apply filters, preserve node identity, and manage availability in one place.
Policy without JSON wrestling	Build selector, URLTest, and fallback strategies from dynamic node groups and route rules.
Safer configuration changes	Generate into a temporary file and run sing-box check before replacing the active configuration.
Runtime visibility	Inspect core state, logs, connections, traffic, synchronization progress, and failures from the browser.
OpenWrt-native packaging	A single IPK includes the service, procd integration, LuCI entry, and iStoreOS metadata.
Local by design	SQLite and cache files stay on your device. No cloud account or external database is required.

Features

• Subscriptions: remote sources, local/manual imports, scheduled synchronization, custom User-Agent, and sync failure reporting.
• Nodes: Clash YAML, sing-box JSON, base64 URI lists, plain URI lists, filters, stable UIDs, flags, latency checks, batch rename, and enable/prefer controls.
• Groups and strategies: dynamic subscription/protocol filters, manual membership, selector, URLTest, fallback, and strategy health checks.
• Routing: manual rules, rule subscriptions, GeoIP/GeoSite assets, Clash rule-provider conversion, priority ordering, and generated previews.
• DNS and TUN: DNS servers, real-IP rules, FakeIP, leak protection, inbound modes, and traffic bypass rules.
• Configuration: modular preview, complete JSON preview, validation, backup, restore, apply, reload, and process/direct-loop protection.
• Operations: core lifecycle control, WebSocket events, logs, connections, traffic, diagnostics, and update checks.
• Custom runtime: integration with ackwrap/sing-box-wrap, including Ackwrap-specific VLESS encryption support.

How It Works

flowchart LR
    A[Remote subscriptions<br/>Local imports] --> B[Parsers and filters]
    B --> C[(SQLite node pool)]
    C --> D[Node groups]
    D --> E[Strategy groups]
    E --> F[Routes, DNS, and TUN]
    F --> G[Config generator]
    G --> H{sing-box check}
    H -->|pass| I[Active config]
    H -->|fail| J[Keep previous config]
    I --> K[Custom sing-box runtime]

Loading

Ackwrap keeps the browser thin and the backend authoritative. Parsing, filtering, synchronization, persistence, config generation, validation, and runtime control all happen in the Go service. REST triggers actions; WebSocket events report progress and final state.

Download

Download the latest build from GitHub Releases.

Artifact	Target	Filename
Combined IPK	OpenWrt x86_64	ackwrap_VERSION-1_x86_64.ipk
Standalone binary	OpenWrt amd64	ackwrap-openwrt-amd64
Combined IPK	OpenWrt ARM64	ackwrap_VERSION-1_aarch64_generic.ipk
Standalone binary	OpenWrt arm64	ackwrap-openwrt-arm64

OpenWrt Quick Install

scp ackwrap_VERSION-1_x86_64.ipk root@ROUTER_IP:/tmp/ackwrap.ipk
ssh root@ROUTER_IP 'opkg install /tmp/ackwrap.ipk'

After installation, open LuCI > Services > Ackwrap and use the launch button to establish an authenticated Ackwrap session.

Use the x86_64 IPK for amd64 routers and aarch64_generic for arm64 routers.

Architecture

Browser
  Vue 3 + TypeScript + Vite
              |
       REST + WebSocket
              |
Go service (Gin)
  handlers -> services -> stores -> SQLite
                  |
          config generator
                  |
           sing-box check
                  |
      custom sing-box runtime

Layer	Technology
Backend	Go, Gin, modernc SQLite, Gorilla WebSocket, robfig/cron
Frontend	Vue 3, TypeScript, Vite, Vue Router, Tailwind CSS 4, DaisyUI
Runtime	sing-box-compatible JSON with an Ackwrap-maintained custom core
Storage	Local SQLite database plus filesystem caches
OpenWrt	procd, UCI, LuCI, and iStoreOS app metadata

Development

Validate

cd backend
go build ./...
go test ./...
go vet ./...

cd ../frontend
npm run build

Run Locally

# Terminal 1
cd backend
ACKWRAP_LISTEN_ADDR=127.0.0.1:8080 go run ./cmd/server

# Terminal 2
cd frontend
npm run dev

The frontend development server runs on http://127.0.0.1:5173 and proxies API requests to the backend on port 8080.

Build Release Artifacts

# Windows, Linux, and OpenWrt amd64
python build.py

# OpenWrt arm64 binary and combined IPK
python build.py --target openwrt --arch arm64

The frontend is embedded into the Go binary. OpenWrt source templates live under openwrt/, and generated artifacts are written to dist/.

Project Layout

backend/          Go API, business services, persistence, parsers, and embedded UI
frontend/         Vue web console
openwrt/          UCI, procd, LuCI, iStoreOS, and package control files
sing-box-wrap/    Ackwrap-maintained sing-box submodule

Upstream projects and references

• SagerNet/sing-box - runtime and configuration model
• MetaCubeX/mihomo - protocol behavior and Clash compatibility reference
• MetaCubeX/metacubexd - dashboard interaction reference
• SagerNet/sing-geoip and sing-geosite - Geo databases
• XTLS/Xray-core - VLESS and Reality ecosystem reference

Interface Preview

IP intelligence and connectivity checks	Routing rules and rule subscriptions
Visual route tracing

License

Ackwrap is released under the MIT License. Third-party code and assets remain under their original licenses.