A modern and elegant dashboard for network traffic visualization and analysis.
#!/usr/bin/env sh
set -eu
PROG="nekoagent"
INSTALL_DIR_DEFAULT="${HOME}/.local/bin"
INSTALL_DIR="${NEKO_INSTALL_DIR:-$INSTALL_DIR_DEFAULT}"
AGENT_BIN="${NEKO_AGENT_BIN:-$INSTALL_DIR/neko-agent}"
CONFIG_DIR="${NEKO_AGENT_CONFIG_DIR:-/etc/neko-agent}"
STATE_DIR="${NEKO_AGENT_STATE_DIR:-/var/run/neko-agent}"
AGENT_REPO="${NEKO_AGENT_REPO:-foru17/neko-master}"
VERSION="0.2.4"
log() {
printf '[%s] %s\n' "$PROG" "$1"
}
err() {
printf '[%s] error: %s\n' "$PROG" "$1" >&2
}
ensure_dirs() {
mkdir -p "$CONFIG_DIR" "$STATE_DIR"
}
config_file() {
name="$1"
printf '%s/%s.env\n' "$CONFIG_DIR" "$name"
}
pid_file() {
name="$1"
printf '%s/%s.pid\n' "$STATE_DIR" "$name"
}
log_file() {
name="$1"
printf '%s/%s.log\n' "$STATE_DIR" "$name"
}
is_running() {
name="$1"
# When a service manager owns this instance, the pidfile is never written
# (cmd_start delegates to systemctl/launchctl/init.d). Ask the service
# manager directly so list/status/restart-all/upgrade reflect reality.
if is_service_managed "$name"; then
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd)
systemctl is-active --quiet "$service"
return $?
;;
launchd)
label="io.neko-master.agent.${name}"
if launchctl list 2>/dev/null | awk -v lbl="$label" 'NR>1 && $3==lbl {found=1} END {exit !found}'; then
return 0
fi
return 1
;;
openwrt)
init_path="/etc/init.d/${service}"
if [ -x "$init_path" ]; then
"$init_path" status >/dev/null 2>&1
return $?
fi
;;
esac
fi
pf="$(pid_file "$name")"
if [ ! -f "$pf" ]; then
return 1
fi
pid="$(cat "$pf" 2>/dev/null || true)"
if [ -z "$pid" ]; then
return 1
fi
kill -0 "$pid" >/dev/null 2>&1
}
# ── Download helpers ────────────────────────────────────────────────────────
wget_with_retries() (
# BusyBox wget may not support --tries; keep its fallback bounded too.
if wget --help 2>&1 | grep -q -- --tries; then
wget --timeout=120 --tries=3 "$@"
return $?
fi
attempt=0
while [ "$attempt" -lt 3 ]; do
if wget --timeout=120 "$@"; then
return 0
else
download_status=$?
fi
attempt=$((attempt + 1))
done
return "$download_status"
)
download_file() {
url="$1"
output="$2"
if command -v curl >/dev/null 2>&1; then
curl -fsSL --connect-timeout 10 --max-time 120 --retry 3 --retry-delay 2 "$url" -o "$output"
return $?
fi
if command -v wget >/dev/null 2>&1; then
wget_with_retries -qO "$output" "$url"
return $?
fi
err "curl or wget is required"
exit 1
}
compute_sha256() {
file="$1"
if command -v sha256sum >/dev/null 2>&1; then
sha256sum "$file" | awk '{print $1}'
return 0
fi
if command -v shasum >/dev/null 2>&1; then
shasum -a 256 "$file" | awk '{print $1}'
return 0
fi
if command -v openssl >/dev/null 2>&1; then
openssl dgst -sha256 "$file" | awk '{print $2}'
return 0
fi
echo ""
}
normalize_os() {
raw="$(uname -s | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz')"
case "$raw" in
linux) echo "linux" ;;
darwin) echo "darwin" ;;
*)
err "unsupported OS: $raw"
exit 1
;;
esac
}
normalize_arch() {
raw="$(uname -m | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz')"
case "$raw" in
x86_64|amd64) echo "amd64" ;;
aarch64|arm64) echo "arm64" ;;
armv7l|armv7|armhf) echo "armv7" ;;
mips) echo "mips" ;;
mipsle) echo "mipsle" ;;
*)
err "unsupported architecture: $raw"
exit 1
;;
esac
}
detect_service_manager() {
os="$(normalize_os)"
if [ "$os" = "linux" ] && [ -f "/etc/openwrt_release" ] && [ -f "/etc/rc.common" ]; then
echo "openwrt"
return 0
fi
if [ "$os" = "linux" ] && command -v systemctl >/dev/null 2>&1 && [ -d "/etc/systemd/system" ]; then
echo "systemd"
return 0
fi
if [ "$os" = "darwin" ] && command -v launchctl >/dev/null 2>&1; then
echo "launchd"
return 0
fi
if command -v crontab >/dev/null 2>&1; then
echo "cron"
return 0
fi
echo "none"
}
service_name_for_instance() {
name="$1"
printf 'neko-agent-%s\n' "$name"
}
# Check if instance is managed by a service manager (systemd/launchd/openwrt)
# Returns 0 if managed, 1 if not
is_service_managed() {
name="$1"
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd)
systemctl is-enabled "$service" >/dev/null 2>&1 && return 0
;;
launchd)
label="io.neko-master.agent.${name}"
plist_path="${HOME}/Library/LaunchAgents/${label}.plist"
[ -f "$plist_path" ] && return 0
;;
openwrt)
init_path="/etc/init.d/${service}"
[ -x "$init_path" ] && return 0
;;
esac
return 1
}
runner_file() {
name="$1"
printf '%s/%s.run.sh\n' "$CONFIG_DIR" "$name"
}
require_linux_root() {
manager="$1"
if [ "$manager" = "systemd" ] || [ "$manager" = "openwrt" ]; then
if [ "$(id -u)" -ne 0 ]; then
err "$manager autostart requires root privileges"
exit 1
fi
fi
}
generate_runner_script() {
name="$1"
rf="$(runner_file "$name")"
cf="$(config_file "$name")"
ensure_dirs
cat > "$rf" <<EOF
#!/usr/bin/env sh
set -eu
AGENT_BIN='$AGENT_BIN'
CONF='$cf'
[ -f "\$CONF" ] || {
echo "[nekoagent] error: config not found: \$CONF" >&2
exit 1
}
. "\$CONF"
: "\${NEKO_SERVER:?missing NEKO_SERVER}"
: "\${NEKO_BACKEND_ID:?missing NEKO_BACKEND_ID}"
: "\${NEKO_BACKEND_TOKEN:?missing NEKO_BACKEND_TOKEN}"
: "\${NEKO_GATEWAY_TYPE:?missing NEKO_GATEWAY_TYPE}"
: "\${NEKO_GATEWAY_URL:?missing NEKO_GATEWAY_URL}"
set -- "\$AGENT_BIN" \
--server-url "\$NEKO_SERVER" \
--backend-id "\$NEKO_BACKEND_ID" \
--backend-token "\$NEKO_BACKEND_TOKEN" \
--gateway-type "\$NEKO_GATEWAY_TYPE" \
--gateway-url "\$NEKO_GATEWAY_URL"
[ -n "\${NEKO_GATEWAY_TOKEN:-}" ] && set -- "\$@" --gateway-token "\$NEKO_GATEWAY_TOKEN"
# Only pass the flag when enabled: older agent binaries reject unknown flags.
case "\${NEKO_GATEWAY_INSECURE_TLS:-}" in 1|t|T|true|TRUE|True) set -- "\$@" --gateway-insecure-tls ;; esac
[ -n "\${NEKO_AGENT_ID:-}" ] && set -- "\$@" --agent-id "\$NEKO_AGENT_ID"
[ -n "\${NEKO_REPORT_INTERVAL:-}" ] && set -- "\$@" --report-interval "\$NEKO_REPORT_INTERVAL"
[ -n "\${NEKO_HEARTBEAT_INTERVAL:-}" ] && set -- "\$@" --heartbeat-interval "\$NEKO_HEARTBEAT_INTERVAL"
[ -n "\${NEKO_GATEWAY_POLL_INTERVAL:-}" ] && set -- "\$@" --gateway-poll-interval "\$NEKO_GATEWAY_POLL_INTERVAL"
[ -n "\${NEKO_REQUEST_TIMEOUT:-}" ] && set -- "\$@" --request-timeout "\$NEKO_REQUEST_TIMEOUT"
[ -n "\${NEKO_REPORT_BATCH_SIZE:-}" ] && set -- "\$@" --report-batch-size "\$NEKO_REPORT_BATCH_SIZE"
[ -n "\${NEKO_MAX_PENDING_UPDATES:-}" ] && set -- "\$@" --max-pending-updates "\$NEKO_MAX_PENDING_UPDATES"
[ -n "\${NEKO_STALE_FLOW_TIMEOUT:-}" ] && set -- "\$@" --stale-flow-timeout "\$NEKO_STALE_FLOW_TIMEOUT"
set -- "\$@" --log="\${NEKO_LOG:-true}"
exec "\$@"
EOF
chmod +x "$rf"
printf '%s\n' "$rf"
}
write_systemd_unit() {
name="$1"
runner="$2"
service="$(service_name_for_instance "$name")"
unit_path="/etc/systemd/system/${service}.service"
cat > "$unit_path" <<EOF
[Unit]
Description=Neko Agent (${name})
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=10
[Service]
Type=simple
ExecStart=${runner}
Restart=always
RestartSec=5
LimitNOFILE=65536
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
EOF
printf '%s\n' "$unit_path"
}
write_openwrt_init() {
name="$1"
runner="$2"
service="$(service_name_for_instance "$name")"
init_path="/etc/init.d/${service}"
cat > "$init_path" <<EOF
#!/bin/sh /etc/rc.common
USE_PROCD=1
START=95
STOP=10
start_service() {
mkdir -p "${STATE_DIR}"
procd_open_instance
procd_set_param command "${runner}"
procd_set_param respawn 3600 5 5
procd_set_param stdout 1
procd_set_param stderr 1
procd_set_param pidfile "$(pid_file "$name")"
procd_close_instance
}
EOF
chmod +x "$init_path"
printf '%s\n' "$init_path"
}
write_launchd_plist() {
name="$1"
runner="$2"
launch_dir="${HOME}/Library/LaunchAgents"
label="io.neko-master.agent.${name}"
plist_path="${launch_dir}/${label}.plist"
mkdir -p "$launch_dir"
cat > "$plist_path" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>${label}</string>
<key>ProgramArguments</key>
<array>
<string>${runner}</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>$(log_file "$name")</string>
<key>StandardErrorPath</key>
<string>$(log_file "$name")</string>
</dict>
</plist>
EOF
printf '%s\n' "$plist_path"
}
enable_autostart_systemd() {
name="$1"
runner="$2"
service="$(service_name_for_instance "$name")"
write_systemd_unit "$name" "$runner" >/dev/null
systemctl daemon-reload
systemctl enable "$service" >/dev/null
systemctl restart "$service"
}
enable_autostart_openwrt() {
name="$1"
runner="$2"
service="$(service_name_for_instance "$name")"
init_path="$(write_openwrt_init "$name" "$runner")"
"$init_path" enable
"$init_path" restart
}
enable_autostart_launchd() {
name="$1"
runner="$2"
plist_path="$(write_launchd_plist "$name" "$runner")"
launchctl unload "$plist_path" >/dev/null 2>&1 || true
launchctl load "$plist_path"
}
enable_autostart_cron() {
name="$1"
runner="$2"
marker="# nekoagent-autostart-${name}"
line="@reboot ${runner} >/dev/null 2>&1 ${marker}"
old_cron="$(crontab -l 2>/dev/null || true)"
{
printf '%s\n' "$old_cron" | grep -v "$marker" || true
printf '%s\n' "$line"
} | crontab -
}
disable_autostart_systemd() {
name="$1"
service="$(service_name_for_instance "$name")"
unit_path="/etc/systemd/system/${service}.service"
systemctl disable "$service" >/dev/null 2>&1 || true
systemctl stop "$service" >/dev/null 2>&1 || true
rm -f "$unit_path"
systemctl daemon-reload >/dev/null 2>&1 || true
}
disable_autostart_openwrt() {
name="$1"
service="$(service_name_for_instance "$name")"
init_path="/etc/init.d/${service}"
if [ -x "$init_path" ]; then
"$init_path" disable >/dev/null 2>&1 || true
"$init_path" stop >/dev/null 2>&1 || true
fi
rm -f "$init_path"
}
disable_autostart_launchd() {
name="$1"
label="io.neko-master.agent.${name}"
plist_path="${HOME}/Library/LaunchAgents/${label}.plist"
launchctl unload "$plist_path" >/dev/null 2>&1 || true
rm -f "$plist_path"
}
disable_autostart_cron() {
name="$1"
marker="# nekoagent-autostart-${name}"
old_cron="$(crontab -l 2>/dev/null || true)"
printf '%s\n' "$old_cron" | grep -v "$marker" | crontab -
}
cmd_enable_autostart() {
name="$1"
ensure_dirs
load_config "$name"
runner="$(generate_runner_script "$name")"
manager="$(detect_service_manager)"
require_linux_root "$manager"
if is_running "$name"; then
cmd_stop "$name" || true
fi
case "$manager" in
openwrt)
enable_autostart_openwrt "$name" "$runner"
;;
systemd)
enable_autostart_systemd "$name" "$runner"
;;
launchd)
enable_autostart_launchd "$name" "$runner"
;;
cron)
enable_autostart_cron "$name" "$runner"
cmd_start "$name"
;;
*)
err "autostart is not supported on this system"
exit 1
;;
esac
log "autostart enabled for '$name' via $manager"
}
cmd_disable_autostart() {
name="$1"
manager="$(detect_service_manager)"
require_linux_root "$manager"
case "$manager" in
openwrt)
disable_autostart_openwrt "$name"
;;
systemd)
disable_autostart_systemd "$name"
;;
launchd)
disable_autostart_launchd "$name"
;;
cron)
disable_autostart_cron "$name"
;;
*)
;;
esac
rm -f "$(runner_file "$name")"
log "autostart disabled for '$name'"
}
# Query GitHub releases API for the latest agent tag (e.g. "agent-v0.2.0").
# Reports HTTP/download errors on stderr and returns non-zero on failure.
#
# The repo publishes BOTH main-app (v*) and agent (agent-v*) releases into the
# same namespace, and either may be marked "latest". So we must NOT use the
# releases/latest endpoint — it can resolve to a main-app release that carries
# no agent binaries. Instead list recent releases and pick the newest agent-v*.
get_latest_remote_tag() (
repo="${1:-$AGENT_REPO}"
api_url="https://api.github.com/repos/${repo}/releases?per_page=100"
token="${GITHUB_TOKEN:-${GITHUB_PAT:-}}"
# Isolate temporary files, credentials and traps from the install/upgrade flow.
umask 077
api_tmp_dir="$(mktemp -d)" || return 1
trap 'rm -rf "$api_tmp_dir"' 0
trap 'exit 1' 1 2 15
request_status=0
if command -v curl >/dev/null 2>&1; then
set -- -fsSL --connect-timeout 10 --max-time 120 --retry 3 --retry-delay 2
if [ -n "$token" ]; then
set -- "$@" -H "Authorization: Bearer $token"
fi
http_code="$(curl "$@" -o "$api_tmp_dir/body" -w '%{http_code}' "$api_url" 2>/dev/null)" || request_status=$?
elif command -v wget >/dev/null 2>&1; then
set -- -S -O "$api_tmp_dir/body"
if [ -n "$token" ]; then
set -- "$@" --header="Authorization: Bearer $token"
fi
wget_with_retries "$@" "$api_url" 2>"$api_tmp_dir/headers" || request_status=$?
http_code="$(awk '$1 ~ /^HTTP\// && $2 ~ /^[0-9][0-9][0-9]$/ {code=$2} END {print code}' "$api_tmp_dir/headers")"
else
err "curl or wget is required"
return 1
fi
case "$http_code" in
401) api_error="GitHub token rejected (401)" ;;
403|429) api_error="GitHub API rate limit or forbidden (HTTP $http_code); set GITHUB_TOKEN" ;;
2??) api_error="" ;;
*) api_error="GitHub API request failed (HTTP ${http_code:-unknown})" ;;
esac
if [ -n "$api_error" ]; then
err "$api_error"
return 1
fi
if [ "$request_status" -ne 0 ]; then
err "GitHub API download failed (HTTP $http_code; downloader exit $request_status)"
return 1
fi
tag="$(awk -F'"' '/"tag_name"/{print $4}' "$api_tmp_dir/body" | grep '^agent-v' | head -1)"
if [ -z "$tag" ]; then
err "no agent-v* release found in GitHub API response"
return 1
fi
printf '%s\n' "$tag"
)
# Return the version string reported by the local neko-agent binary, or "".
get_local_binary_version() {
if [ -x "$AGENT_BIN" ]; then
"$AGENT_BIN" --version 2>/dev/null | head -1 || true
fi
}
is_version_arg() {
v="${1:-}"
case "$v" in
""|latest|agent-v*|v[0-9]*|[0-9]*)
return 0
;;
*)
return 1
;;
esac
}
normalize_version_tag() {
version_arg="${1:-latest}"
if [ "$version_arg" = "latest" ]; then
printf 'latest\n'
return 0
fi
case "$version_arg" in
agent-v*)
printf '%s\n' "$version_arg"
;;
v*)
printf 'agent-%s\n' "$version_arg"
;;
*)
printf 'agent-v%s\n' "$version_arg"
;;
esac
}
target_plain_from_tag() {
tag="$1"
printf '%s\n' "${tag#agent-v}"
}
# ── Update / download binary ────────────────────────────────────────────────
# Download, verify, and install a new neko-agent binary.
# Usage: do_download_binary <version_arg> <os> <arch>
# version_arg: "latest" or "agent-v0.2.0" style tag
do_download_binary() {
version_arg="$1"
os="$2"
arch="$3"
if [ "$version_arg" = "latest" ]; then
# Resolve to a concrete agent-v* tag; releases/latest may be a main-app
# release with no agent binaries (→ 404).
tag="$(get_latest_remote_tag "$AGENT_REPO")" || tag=""
if [ -z "$tag" ]; then
err "could not determine latest agent version from GitHub API"
return 1
fi
release_path="releases/download/${tag}"
asset="neko-agent_${os}_${arch}.tar.gz"
else
# normalise: accept bare "0.2.0" or full "agent-v0.2.0"
case "$version_arg" in
agent-v*) tag="$version_arg" ;;
v*) tag="agent-${version_arg}" ;;
*) tag="agent-v${version_arg}" ;;
esac
release_path="releases/download/${tag}"
asset="neko-agent_${tag}_${os}_${arch}.tar.gz"
fi
package_url="https://github.com/${AGENT_REPO}/${release_path}/${asset}"
checksums_url="https://github.com/${AGENT_REPO}/${release_path}/checksums.txt"
tmp_dir="$(mktemp -d)"
# shellcheck disable=SC2064
trap "rm -rf '$tmp_dir'" EXIT INT TERM
archive_path="$tmp_dir/neko-agent.tar.gz"
checksums_path="$tmp_dir/checksums.txt"
log "downloading $package_url"
download_file "$package_url" "$archive_path"
log "verifying checksum..."
download_file "$checksums_url" "$checksums_path"
expected_hash="$(awk -v a="$asset" '$2 == a {print $1}' "$checksums_path" | head -n 1)"
if [ -z "$expected_hash" ]; then
err "cannot find checksum for $asset in checksums.txt"
exit 1
fi
actual_hash="$(compute_sha256 "$archive_path")"
if [ -z "$actual_hash" ]; then
err "no sha256 tooling found (sha256sum / shasum / openssl)"
exit 1
fi
if [ "$expected_hash" != "$actual_hash" ]; then
err "checksum mismatch for $asset"
err " expected: $expected_hash"
err " actual: $actual_hash"
exit 1
fi
mkdir -p "$tmp_dir/extract"
tar -xzf "$archive_path" -C "$tmp_dir/extract"
new_binary="$tmp_dir/extract/neko-agent"
if [ ! -f "$new_binary" ]; then
err "extracted archive does not contain neko-agent"
exit 1
fi
chmod +x "$new_binary"
install_dir="$(dirname "$AGENT_BIN")"
mkdir -p "$install_dir"
mv "$new_binary" "$AGENT_BIN"
log "binary installed: $AGENT_BIN"
}
# Download and install the manager script itself.
# Usage: do_download_manager <agent-tag>
# agent-tag: e.g. "agent-v0.2.0"
do_download_manager() {
tag="$1"
manager_url="https://raw.githubusercontent.com/${AGENT_REPO}/${tag}/apps/agent/nekoagent"
tmp_dir="$(mktemp -d)"
# shellcheck disable=SC2064
trap "rm -rf '$tmp_dir'" EXIT INT TERM
new_manager="$tmp_dir/nekoagent"
log "downloading manager script: $manager_url"
download_file "$manager_url" "$new_manager"
chmod +x "$new_manager"
mkdir -p "$INSTALL_DIR"
manager_target="$INSTALL_DIR/nekoagent"
mv "$new_manager" "$manager_target"
log "manager installed: $manager_target"
current_path="$(command -v "$PROG" 2>/dev/null || true)"
if [ -n "$current_path" ] && [ "$current_path" != "$manager_target" ] && [ -w "$current_path" ]; then
if [ -e "$current_path" ] && [ -e "$manager_target" ] && [ "$current_path" -ef "$manager_target" ]; then
log "manager path already points to installed target: $current_path"
else
cp "$manager_target" "$current_path"
chmod +x "$current_path" || true
log "manager synced to: $current_path"
fi
fi
}
# ── Commands ────────────────────────────────────────────────────────────────
version() {
manager_ver="$VERSION"
binary_ver="$(get_local_binary_version)"
if [ -z "$binary_ver" ]; then
binary_ver="(binary not found)"
fi
printf 'nekoagent %s\n' "$manager_ver"
printf 'neko-agent %s\n' "$binary_ver"
}
usage() {
cat <<EOF
Neko Agent Manager v${VERSION}
Usage:
$PROG init <name> [KEY=VALUE ...] Create/overwrite config file
$PROG add <name> [flags/options] Quick add new backend instance
$PROG start <name> Start agent instance
$PROG stop <name> Stop agent instance
$PROG restart <name> Restart agent instance
$PROG status <name> Show instance status
$PROG logs <name> Tail logs
$PROG enable-autostart <name> Register boot autostart and start via service manager
$PROG disable-autostart <name> Remove boot autostart registration
$PROG list List configured instances
$PROG restart-all Restart all running instances
$PROG upgrade [version] Upgrade manager+binary and restart running instances
$PROG remove <name> Remove instance config/runtime
$PROG delete <name> Alias of remove
$PROG uninstall Uninstall nekoagent + binaries
$PROG version Show manager and binary version
$PROG help Show this help
Quick add with flags (auto-starts by default):
$PROG add <name> \
--server-url <url> \
--backend-id <id> \
--backend-token <token> \
--gateway-type <clash|surge> \
--gateway-url <url> \
[--gateway-token <token>] \
[--gateway-insecure-tls] \
[--no-start] # skip auto-start after add
Upgrade examples:
$PROG upgrade # upgrade to latest release
$PROG upgrade agent-v0.2.0 # upgrade to specific version
Config and runtime paths:
CONFIG_DIR=$CONFIG_DIR
STATE_DIR=$STATE_DIR
AGENT_BIN=$AGENT_BIN
Required config keys:
NEKO_SERVER, NEKO_BACKEND_ID, NEKO_BACKEND_TOKEN, NEKO_GATEWAY_TYPE, NEKO_GATEWAY_URL
Optional keys:
NEKO_GATEWAY_TOKEN, NEKO_GATEWAY_INSECURE_TLS, NEKO_LOG, NEKO_AGENT_ID, NEKO_REPORT_INTERVAL,
NEKO_HEARTBEAT_INTERVAL, NEKO_GATEWAY_POLL_INTERVAL, NEKO_REQUEST_TIMEOUT,
NEKO_REPORT_BATCH_SIZE, NEKO_MAX_PENDING_UPDATES, NEKO_STALE_FLOW_TIMEOUT
Examples:
# Add and start a new backend
$PROG add home-surge --server-url http://10.0.0.210:3000 --backend-id 3 \\
--backend-token ag_xxx --gateway-type surge --gateway-url http://10.0.0.210:9091 \\
--gateway-token xxx
# List all instances
$PROG list
# Check status
$PROG status home-surge
# Register startup persistence
$PROG enable-autostart home-surge
# View logs
$PROG logs home-surge
# Global upgrade (recommended)
$PROG upgrade
$PROG upgrade agent-v0.2.0
# Remove instance
$PROG remove home-surge
EOF
}
require_config_key() {
key="$1"
eval "val=\${$key:-}"
if [ -z "$val" ]; then
err "missing required key in config: $key"
exit 1
fi
}
load_config() {
name="$1"
cf="$(config_file "$name")"
if [ ! -f "$cf" ]; then
err "config not found: $cf"
exit 1
fi
# shellcheck disable=SC1090
. "$cf"
require_config_key "NEKO_SERVER"
require_config_key "NEKO_BACKEND_ID"
require_config_key "NEKO_BACKEND_TOKEN"
require_config_key "NEKO_GATEWAY_TYPE"
require_config_key "NEKO_GATEWAY_URL"
}
build_agent_args() {
set -- \
--server-url "$NEKO_SERVER" \
--backend-id "$NEKO_BACKEND_ID" \
--backend-token "$NEKO_BACKEND_TOKEN" \
--gateway-type "$NEKO_GATEWAY_TYPE" \
--gateway-url "$NEKO_GATEWAY_URL"
if [ -n "${NEKO_GATEWAY_TOKEN:-}" ]; then
set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
fi
# Only pass the flag when enabled: older agent binaries reject unknown flags.
case "${NEKO_GATEWAY_INSECURE_TLS:-}" in
1|t|T|true|TRUE|True) set -- "$@" --gateway-insecure-tls ;;
esac
if [ -n "${NEKO_AGENT_ID:-}" ]; then
set -- "$@" --agent-id "$NEKO_AGENT_ID"
fi
if [ -n "${NEKO_REPORT_INTERVAL:-}" ]; then
set -- "$@" --report-interval "$NEKO_REPORT_INTERVAL"
fi
if [ -n "${NEKO_HEARTBEAT_INTERVAL:-}" ]; then
set -- "$@" --heartbeat-interval "$NEKO_HEARTBEAT_INTERVAL"
fi
if [ -n "${NEKO_GATEWAY_POLL_INTERVAL:-}" ]; then
set -- "$@" --gateway-poll-interval "$NEKO_GATEWAY_POLL_INTERVAL"
fi
if [ -n "${NEKO_REQUEST_TIMEOUT:-}" ]; then
set -- "$@" --request-timeout "$NEKO_REQUEST_TIMEOUT"
fi
if [ -n "${NEKO_REPORT_BATCH_SIZE:-}" ]; then
set -- "$@" --report-batch-size "$NEKO_REPORT_BATCH_SIZE"
fi
if [ -n "${NEKO_MAX_PENDING_UPDATES:-}" ]; then
set -- "$@" --max-pending-updates "$NEKO_MAX_PENDING_UPDATES"
fi
if [ -n "${NEKO_STALE_FLOW_TIMEOUT:-}" ]; then
set -- "$@" --stale-flow-timeout "$NEKO_STALE_FLOW_TIMEOUT"
fi
log_enabled="${NEKO_LOG:-true}"
set -- "$@" --log="$log_enabled"
printf '%s\n' "$*"
}
cmd_init() {
name="$1"
shift
ensure_dirs
cf="$(config_file "$name")"
umask 077
: > "$cf"
for kv in "$@"; do
case "$kv" in
*=*) printf '%s\n' "$kv" >> "$cf" ;;
*)
err "invalid key=value pair: $kv"
exit 1
;;
esac
done
log "config written: $cf"
}
# Quick add with flags instead of KEY=VALUE pairs
cmd_add() {
if [ "$#" -lt 6 ]; then
err "add requires: <name> --server-url <url> --backend-id <id> --backend-token <token> --gateway-type <type> --gateway-url <url>"
echo ""
echo "Usage: $PROG add <name> --server-url <url> --backend-id <id> --backend-token <token> --gateway-type <clash|surge> --gateway-url <url> [--gateway-token <token>] [--gateway-insecure-tls] [--auto-start]"
exit 1
fi
name="$1"
shift
# Parse flags
server_url=""
backend_id=""
backend_token=""
gateway_type=""
gateway_url=""
gateway_token=""
gateway_insecure_tls="${NEKO_GATEWAY_INSECURE_TLS:-false}"
auto_start="true" # default: start immediately after add
while [ "$#" -gt 0 ]; do
case "$1" in
--server-url)
server_url="$2"
shift 2
;;
--backend-id)
backend_id="$2"
shift 2
;;
--backend-token)
backend_token="$2"
shift 2
;;
--gateway-type)
gateway_type="$2"
shift 2
;;
--gateway-url)
gateway_url="$2"
shift 2
;;
--gateway-token)
gateway_token="$2"
shift 2
;;
--gateway-insecure-tls)
gateway_insecure_tls="true"
shift
;;
--gateway-insecure-tls=*)
gateway_insecure_tls="${1#*=}"
shift
;;
--auto-start)
auto_start="true"
shift
;;
--no-start)
auto_start="false"
shift
;;
*)
err "unknown flag: $1"
exit 1
;;
esac
done
# Validate required fields
if [ -z "$server_url" ] || [ -z "$backend_id" ] || [ -z "$backend_token" ] || [ -z "$gateway_type" ] || [ -z "$gateway_url" ]; then
err "missing required flags"
echo "Required: --server-url, --backend-id, --backend-token, --gateway-type, --gateway-url"
exit 1
fi
# Build config
config_vars=""
config_vars="$config_vars NEKO_SERVER=$server_url"
config_vars="$config_vars NEKO_BACKEND_ID=$backend_id"
config_vars="$config_vars NEKO_BACKEND_TOKEN=$backend_token"
config_vars="$config_vars NEKO_GATEWAY_TYPE=$gateway_type"
config_vars="$config_vars NEKO_GATEWAY_URL=$gateway_url"
config_vars="$config_vars NEKO_GATEWAY_INSECURE_TLS=$gateway_insecure_tls"
if [ -n "$gateway_token" ]; then
config_vars="$config_vars NEKO_GATEWAY_TOKEN=$gateway_token"
fi
# Initialize config
cf="$(config_file "$name")"
if [ -f "$cf" ]; then
log "updating existing instance '$name' config"
if is_running "$name"; then
log "stopping existing instance '$name' before reconfiguring..."
cmd_stop "$name" || true
fi
fi
# shellcheck disable=SC2086
cmd_init "$name" $config_vars
log "instance '$name' added successfully"
# Auto-start if requested
if [ "$auto_start" = "true" ]; then
cmd_start "$name"
fi
}
cmd_start() {
name="$1"
ensure_dirs
# If managed by service manager, delegate to it
if is_service_managed "$name"; then
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd) systemctl start "$service" ;;
launchd)
label="io.neko-master.agent.${name}"
plist_path="${HOME}/Library/LaunchAgents/${label}.plist"
launchctl load "$plist_path" 2>/dev/null || true
;;
openwrt) "/etc/init.d/${service}" start ;;
esac
log "instance '$name' started via $manager"
return 0
fi
if [ ! -x "$AGENT_BIN" ]; then
err "agent binary not found/executable: $AGENT_BIN"
exit 1
fi
if is_running "$name"; then
log "instance '$name' already running (pid $(cat "$(pid_file "$name")"))"
return 0
fi
load_config "$name"
args="$(build_agent_args)"
lf="$(log_file "$name")"
pf="$(pid_file "$name")"
# shellcheck disable=SC2086
nohup "$AGENT_BIN" $args >> "$lf" 2>&1 &
pid=$!
printf '%s\n' "$pid" > "$pf"
log "instance '$name' started, pid=$pid, log=$lf"
}
cmd_stop() {
name="$1"
# If managed by service manager, delegate to it
if is_service_managed "$name"; then
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd) systemctl stop "$service" ;;
launchd)
label="io.neko-master.agent.${name}"
plist_path="${HOME}/Library/LaunchAgents/${label}.plist"
launchctl unload "$plist_path" 2>/dev/null || true
;;
openwrt) "/etc/init.d/${service}" stop ;;
esac
rm -f "$(pid_file "$name")"
log "instance '$name' stopped via $manager"
return 0
fi
pf="$(pid_file "$name")"
if ! is_running "$name"; then
rm -f "$pf"
log "instance '$name' is not running"
return 0
fi
pid="$(cat "$pf")"
kill "$pid" >/dev/null 2>&1 || true
# Wait up to 12s for graceful shutdown (agent needs up to 10s for final flush)
i=0
while [ "$i" -lt 12 ] && kill -0 "$pid" >/dev/null 2>&1; do
sleep 1
i=$((i + 1))
done
if kill -0 "$pid" >/dev/null 2>&1; then
kill -9 "$pid" >/dev/null 2>&1 || true
fi
rm -f "$pf"
log "instance '$name' stopped"
}
cmd_status() {
name="$1"
managed=""
if is_service_managed "$name"; then
managed=" (managed by $(detect_service_manager))"
fi
if is_running "$name"; then
pid=""
if is_service_managed "$name"; then
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd)
pid="$(systemctl show -p MainPID --value "$service" 2>/dev/null || true)"
;;
esac
fi
if [ -z "$pid" ] || [ "$pid" = "0" ]; then
pf="$(pid_file "$name")"
[ -f "$pf" ] && pid="$(cat "$pf" 2>/dev/null || true)"
fi
if [ -n "$pid" ] && [ "$pid" != "0" ]; then
log "instance '$name' is running (pid $pid)${managed}"
else
log "instance '$name' is running${managed}"
fi
exit 0
fi
log "instance '$name' is stopped${managed}"
exit 1
}
cmd_logs() {
name="$1"
# Service-managed instances don't write the wrapper's $lf; route to the
# appropriate native log source instead.
if is_service_managed "$name"; then
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd)
journalctl -u "$service" -f --no-pager
return 0
;;
openwrt)
# procd_set_param stdout/stderr 1 routes to syslog → logread
if command -v logread >/dev/null 2>&1; then
logread -e "$service" -f
return 0
fi
;;
launchd)
# launchd plist writes to $lf directly, fall through to tail
;;
esac
fi
lf="$(log_file "$name")"
if [ ! -f "$lf" ]; then
err "log file not found: $lf"
exit 1
fi
tail -f "$lf"
}
cmd_list() {
ensure_dirs
found=false
for f in "$CONFIG_DIR"/*.env; do
if [ ! -e "$f" ]; then
continue
fi
found=true
name="$(basename "$f" .env)"
if is_running "$name"; then
status="running"
else
status="stopped"
fi
managed=""
if is_service_managed "$name"; then
managed=" [$(detect_service_manager)]"
fi
# Load config to show backend info
# shellcheck disable=SC1090
. "$f"
printf '%-20s %-10s backend-id=%s gateway=%s%s\n' "$name" "$status" "${NEKO_BACKEND_ID:-?}" "${NEKO_GATEWAY_TYPE:-?}" "$managed"
done
if [ "$found" = false ]; then
log "no instances configured"
fi
}
cmd_restart_all() {
ensure_dirs
restarted_any=false
for f in "$CONFIG_DIR"/*.env; do
if [ ! -e "$f" ]; then
continue
fi
name="$(basename "$f" .env)"
if is_running "$name"; then
log "restarting '$name'..."
cmd_stop "$name" || true
cmd_start "$name"
restarted_any=true
fi
done
if [ "$restarted_any" = false ]; then
log "no running instances found"
fi
}
cmd_upgrade_global() {
version_arg="${1:-latest}"
os="$(normalize_os)"
arch="$(normalize_arch)"
if [ "$version_arg" = "latest" ]; then
log "querying GitHub for latest release..."
target_tag="$(get_latest_remote_tag "$AGENT_REPO")" || target_tag=""
if [ -z "$target_tag" ]; then
err "failed to determine latest version from GitHub API"
err "hint: check network access or specify a version: $PROG upgrade agent-v0.2.0"
exit 1
fi
else
target_tag="$(normalize_version_tag "$version_arg")"
fi
target_plain="$(target_plain_from_tag "$target_tag")"
local_version="$(get_local_binary_version)"
binary_changed=false
if [ -n "$local_version" ] && [ "$local_version" = "$target_plain" ]; then
log "binary already at $local_version, no binary download needed"
else
log "upgrading binary: ${local_version:-not installed} -> $target_plain"
do_download_binary "$target_tag" "$os" "$arch"
binary_changed=true
fi
do_download_manager "$target_tag"
restarted_any=false
for f in "$CONFIG_DIR"/*.env; do
if [ ! -e "$f" ]; then
continue
fi
name="$(basename "$f" .env)"
if is_running "$name"; then
log "restarting running instance '$name'..."
if is_service_managed "$name"; then
# Re-generate runner script and update service unit for managed instances
load_config "$name"
runner="$(generate_runner_script "$name")"
manager="$(detect_service_manager)"
service="$(service_name_for_instance "$name")"
case "$manager" in
systemd)
write_systemd_unit "$name" "$runner" >/dev/null
systemctl daemon-reload
systemctl restart "$service"
;;
launchd)
plist_path="$(write_launchd_plist "$name" "$runner")"
launchctl unload "$plist_path" >/dev/null 2>&1 || true
launchctl load "$plist_path"
;;
openwrt)
write_openwrt_init "$name" "$runner" >/dev/null
"/etc/init.d/${service}" restart
;;
esac
else
cmd_stop "$name" || true
cmd_start "$name"
fi
restarted_any=true
fi
done
if [ "$restarted_any" = false ]; then
log "no running instances found; binary upgraded globally"
fi
log "upgrade complete: manager + binary at version $target_plain"
}
cmd_remove() {
name="$1"
cmd_disable_autostart "$name" >/dev/null 2>&1 || true
if is_running "$name"; then
cmd_stop "$name"
fi
rm -f "$(pid_file "$name")"
rm -f "$(log_file "$name")"
rm -f "$(runner_file "$name")"
cf="$(config_file "$name")"
if [ -f "$cf" ]; then
rm -f "$cf"
fi
log "instance '$name' removed"
}
cmd_uninstall() {
rm -f "$AGENT_BIN"
rm -f "$INSTALL_DIR/nekoagent"
rm -f "/usr/local/bin/neko-agent" "/usr/local/bin/nekoagent"
log "binaries removed"
log "note: instance config files remain in $CONFIG_DIR (use '$PROG remove <name>' if needed)"
}
main() {
if [ "$#" -lt 1 ]; then
usage
exit 1
fi
cmd="$1"
shift
case "$cmd" in
init)
if [ "$#" -lt 2 ]; then
usage
exit 1
fi
cmd_init "$@"
;;
add)
if [ "$#" -lt 6 ]; then
usage
exit 1
fi
cmd_add "$@"
;;
start|stop|restart|status|logs|enable-autostart|disable-autostart)
if [ "$#" -ne 1 ]; then
usage
exit 1
fi
case "$cmd" in
start) cmd_start "$1" ;;
stop) cmd_stop "$1" ;;
restart) cmd_stop "$1" || true; cmd_start "$1" ;;
status) cmd_status "$1" ;;
logs) cmd_logs "$1" ;;
enable-autostart) cmd_enable_autostart "$1" ;;
disable-autostart) cmd_disable_autostart "$1" ;;
esac
;;
upgrade)
if [ "$#" -gt 1 ]; then
usage
exit 1
fi
if [ "$#" -eq 1 ] && ! is_version_arg "$1"; then
err "upgrade only accepts an optional version (e.g. agent-v0.2.0), not instance name"
exit 1
fi
cmd_upgrade_global "${1:-latest}"
;;
update)
err "'update' command has been removed; use '$PROG upgrade [version]'"
exit 1
;;
remove|delete)
if [ "$#" -ne 1 ]; then
usage
exit 1
fi
cmd_remove "$1"
;;
uninstall)
if [ "$#" -ne 0 ]; then
err "uninstall does not accept instance name; use '$PROG remove <name>'"
usage
exit 1
fi
cmd_uninstall
;;
list)
cmd_list
;;
restart-all)
cmd_restart_all
;;
version|-v|--version)
version
;;
help|-h|--help)
usage
;;
*)
err "unknown command: $cmd"
usage
exit 1
;;
esac
}
main "$@"