aonectl

@onslaughtsnail/aonectl is a small AOne helper built around one stable aonectl flow.

Goals:

• consumers do not build images locally
• AOne runs from the same Docker image on Linux, WSL2, and macOS SSH targets
• install and uninstall are reversible
• Linux local node and macOS SSH node share one control surface
• WSL2 can run AOne in an isolated Docker runtime while Windows routes selected intranet traffic through it
• the main goal is low-friction daily use, not a heavy product contract

Layout

• install.sh: consumer installer
• uninstall.sh: consumer runtime cleanup entrypoint
• bundle/: runtime files copied to the target machine
• publisher/: maintainer-only image build and push assets

Consumer Quick Start

npm install -g @onslaughtsnail/aonectl@latest
aonectl install
aonectl remote show
aonectl config
aonectl login
aonectl apply
aonectl doctor

Publisher Quick Start

cd publisher
./build-push.sh --tag latest

Default registry repo:

ctyun-srdart.srdcloud.cn/hunheyuncloud/hunheyuncloud-release-docker-local/aonectl

Current Delivery Shape

• Runtime image is expected to be prebuilt and pushed as a multi-arch linux/amd64 plus linux/arm64 image
• Consumer install path defaults to ~/.local/share/aonectl
• Shell integration supports zsh and bash
• Linux local node supports docker, nerdctl, and podman
• WSL2 supports one explicit mode: Docker inside WSL2 with --network host, intended for Windows route mode with WSL as the next hop
• macOS uses SSH mode and expects a reachable Linux host over passwordless SSH
• macOS SSH mode always runs AOne in a privileged Docker container on the target host with host networking
• SSH install asks for the target host, validates key-based SSH plus sudo -n, checks Docker, and can install Docker Engine after confirmation when it is missing
• SSH target and helper directory are stored in aonectl.conf and can be reviewed or changed with aonectl remote
• local mode assumes the selected runtime can run privileged containers with /dev/net/tun; rootless setups are outside the guaranteed path
• WSL2 mode assumes NAT networking is enabled on the Windows host and Docker Engine runs inside the WSL distribution

WSL2 + Windows Host Mode

The supported Windows path is intentionally narrow:

• run aonectl install from inside the WSL2 distribution
• use Docker Engine inside WSL, not Docker Desktop integration as the primary contract
• run the AOne container with Docker host networking
• keep Windows on WSL NAT networking so Windows can use the WSL address as a route gateway
• route IP and IP-CIDR rules by adding Windows static routes to the WSL address
• keep PAC as an explicit fallback for applications that honor Windows user proxy settings

Host setup checklist:

# %UserProfile%\.wslconfig
[wsl2]
networkingMode=nat
dnsTunneling=true
autoProxy=false
firewall=true

Then restart WSL:

wsl --shutdown

Inside WSL, enable systemd when needed:

sudo sh -lc "printf '[boot]\nsystemd=true\n' > /etc/wsl.conf"

Route mode must be run from an elevated PowerShell because Windows static routes require administrator rights:

aonectl apply
aonectl clean

If Hyper-V firewall inbound was opened during testing, close it again after adding precise allow rules:

Set-NetFirewallHyperVVMSetting -Name <WSL_NAME_OR_ID> -DefaultInboundAction Block

Generate a PAC file from the current RULES:

aonectl pac > aonectl.pac

The standalone aonectl pac output routes matching DOMAIN, DOMAIN-SUFFIX, IP, and IP-CIDR rules to 127.0.0.1:1081 and leaves all other traffic direct.

When invoked from Windows, aonectl apply defaults to route mode: it starts the WSL AOne node, enables WSL forwarding/NAT to the AOne utun device, and adds Windows static routes for IP and IP-CIDR rules. For DOMAIN and DOMAIN-SUFFIX rules, it starts a Windows-side Node DNS proxy on 127.0.0.1:53, points NRPT rules at that proxy, forwards matching DNS queries to the AOne internal DNS, and adds dynamic /32 routes for returned A records.

On Windows, aonectl login and aonectl apply register and start a current-user scheduled task named aonectl WSL Keepalive. The task keeps WSL resident by running wsl.exe -d <distro> -- bash -lc "exec sleep infinity" at logon and immediately after setup. aonectl clean and aonectl uninstall remove this task.

Set AONE_WINDOWS_MODE=pac to use the PAC fallback. In PAC mode, aonectl apply serves the generated PAC on http://127.0.0.1:1082/aonectl.pac and installs it as the current user's AutoConfigURL; aonectl clean restores the previous value.

Notes

• The runtime state is user-scoped
• Login state is still user and device specific and should not be shared
• login.yaml, ctEAO.did, and the AOne DB are persisted locally or on the remote target
• uninstall.sh removes shell hook blocks, managed containers, managed network, and local runtime state; it does not remove the aonectl program files themselves
• config and login use the original AOne interactive flow; no host-side Python or Node wrapper is required
• local host routing and split-DNS point directly at the node IP 172.30.0.2:53; 10530 is no longer part of the default path
• WSL2 host-network mode does not use 172.30.0.2; Windows route mode uses the WSL NAT IPv4 address as the next hop
• WSL2 host-network mode disables the container DNS listener to avoid conflicting with WSL's own DNS service
• Windows route mode uses the installed Node runtime for the local DNS proxy; it does not require Python inside WSL
• SSH mode uses a local DNS proxy on macOS and prefers Node from the npm install environment; Python 3 is only a fallback
• If the target host cannot pull the runtime image, prepare it manually with docker login/docker pull or docker load -i aonectl-image.tar, then rerun aonectl install

Support Boundary

Implemented now:

• aonectl as the single user-facing command
• local Linux node with runtime selection
• WSL2 Docker host-network node with preflight checks and Windows setup guidance
• Windows route mode for IP and IP-CIDR rules through WSL NAT
• Windows NRPT DNS split-routing for DOMAIN and DOMAIN-SUFFIX rules through a Node DNS proxy
• PAC generation from existing RULES
• macOS SSH node that runs the AOne container on the target Linux host and applies local macOS routing via the integrated helper
• automatic remote Docker check and optional Docker Engine install for RPM-based Linux hosts
• reversible install and uninstall
• multi-arch image publishing

Not implemented now:

• public mainland-accessible runtime image registry; the default image currently remains the SRDCloud registry
• transparent Windows TUN/WFP interception
• raw ctr support without nerdctl
• non-RPM remote distributions for SSH mode