A modern and elegant dashboard for network traffic visualization and analysis.
Agent Install Guide
中文 | English
Supported targets
Release artifacts are published for:
darwin-amd64darwin-arm64linux-amd64linux-arm64linux-armv7linux-mipslinux-mipsle
Install via script (recommended)
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
| env NEKO_SERVER='http://your-panel:3000' \
NEKO_BACKEND_ID='13' \
NEKO_BACKEND_TOKEN='ag_xxx' \
NEKO_GATEWAY_TYPE='clash' \
NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
sh
Optional env:
NEKO_GATEWAY_TOKEN: gateway auth tokenNEKO_AGENT_VERSION:latest(default) or explicit tag likeagent-v0.2.0NEKO_INSTALL_DIR: install directory (default$HOME/.local/bin)NEKO_AUTO_START:true|false(defaulttrue, starts immediately and auto-registers boot autostart)NEKO_LOG:true|false(defaulttrue)NEKO_LOG_FILE: runtime log file pathNEKO_PACKAGE_URL: custom package URL overrideNEKO_CHECKSUMS_URL: custom checksums URL overrideNEKO_INSTANCE_NAME: instance name fornekoagentmanager (defaultbackend-<id>)NEKO_BIN_LINK_MODE:auto|true|falsefor symlink into global bin dir (defaultauto)NEKO_LINK_DIR: global bin dir for symlink (default/usr/local/bin)GITHUB_TOKEN: token for GitHub API queries; falls back toGITHUB_PATwhen empty
Set AGENT_HEARTBEAT_TIMEOUT_MS in the collector process environment to adjust how long an agent may stay silent before it is shown offline (backend list, automatic health checks and manual test) (milliseconds, default 90000, minimum 15000). The default allows 3 × the agent's default 30-second heartbeat interval to tolerate delayed reports; this is a collector setting, not an agent install option.
After install, manage agent with:
nekoagent status <instance>
nekoagent logs <instance>
nekoagent restart <instance>
nekoagent upgrade
nekoagent upgrade agent-vX.Y.Z
nekoagent remove <instance>
Uninstall binaries:
nekoagent uninstall
GitHub API rate limit / private mirrors
If fetching the latest version hits GitHub's anonymous API rate limit, set GITHUB_TOKEN and retry:
GITHUB_TOKEN='<github-token>' nekoagent upgrade
For installation, set the same variable before running a downloaded install.sh, preserving your existing NEKO_* installation settings:
GITHUB_TOKEN='<github-token>' \
NEKO_SERVER='http://your-panel:3000' \
NEKO_BACKEND_ID='13' \
NEKO_BACKEND_TOKEN='ag_xxx' \
NEKO_GATEWAY_TYPE='clash' \
NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
sh ./install.sh
A non-empty GITHUB_TOKEN takes precedence; otherwise, GITHUB_PAT is used. The token is sent only to https://api.github.com, never to release binaries, raw files, or mirror download URLs, and is not saved in instance configs. If installation with a private mirror still queries GitHub for the latest version, this variable authenticates that API query; access to the mirror download itself must be handled separately.
GitHub token rejected (401): the token is invalid or expired; replace it and retry.GitHub API rate limit or forbidden (HTTP 403); set GITHUB_TOKEN(orHTTP 429): the API is rate-limited or access is forbidden; set a valid token and check permissions or wait for the limit to reset.
Manual install
- Download the correct tarball from GitHub Releases
- Verify hash using
checksums.txt - Extract
neko-agent - Run executable with backend parameters
Optional gateway flags
| Flag | Environment variable | Default | Description |
|---|---|---|---|
--gateway-insecure-tls |
NEKO_GATEWAY_INSECURE_TLS |
false |
Skip gateway API TLS certificate verification for self-signed Surge http-api-tls / mihomo external-controller-tls certificates. Use only on a trusted LAN. Server reporting still verifies certificates. |
Append --gateway-insecure-tls to nekoagent add to persist the setting. For an existing instance, set NEKO_GATEWAY_INSECURE_TLS=true in /etc/neko-agent/<name>.env and restart it.
OpenWrt note
Before build selection, check architecture:
uname -m
opkg print-architecture
Common mapping:
x86_64->linux-amd64aarch64->linux-arm64armv7*->linux-armv7mips->linux-mipsmipsle->linux-mipsle
What gets installed
The install script places two binaries into NEKO_INSTALL_DIR (default ~/.local/bin):
neko-agent— the data collection daemon (runs continuously, reports to panel)nekoagent— the CLI manager for lifecycle operations (start / stop / upgrade / remove)
The nekoagent manager stores:
- Instance configs in
CONFIG_DIR(default/etc/neko-agent/<name>.env) - PID and log files in
STATE_DIR(default/var/run/neko-agent/)
Autostart on system boot
Since agent-v0.2.1, when NEKO_AUTO_START=true the installer automatically attempts to
register boot autostart (systemd / OpenWrt procd / launchd / cron fallback).
If permissions are insufficient or the platform is unsupported, configure a system service
manually so the agent survives reboots.
Linux — systemd
Create /etc/systemd/system/neko-agent-<instance>.service (replace <instance> with your
instance name, e.g. backend-1):
[Unit]
Description=Neko Agent (<instance>)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
EnvironmentFile=/etc/neko-agent/<instance>.env
ExecStart=/usr/local/bin/neko-agent \
--server-url ${NEKO_SERVER} \
--backend-id ${NEKO_BACKEND_ID} \
--backend-token ${NEKO_BACKEND_TOKEN} \
--gateway-type ${NEKO_GATEWAY_TYPE} \
--gateway-url ${NEKO_GATEWAY_URL}
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
If NEKO_GATEWAY_TOKEN is set, append it to ExecStart:
ExecStart=/usr/local/bin/neko-agent \
...
--gateway-token ${NEKO_GATEWAY_TOKEN}
Enable and start:
systemctl daemon-reload
systemctl enable neko-agent-<instance>
systemctl start neko-agent-<instance>
systemctl status neko-agent-<instance>
View logs:
journalctl -u neko-agent-<instance> -f
Note: If
neko-agentis installed to~/.local/bin(non-root), adjustExecStartpath accordingly and consider running the service under a non-root user.
macOS — launchd
Create ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist:
<?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>io.neko-master.agent.<instance></string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/neko-agent</string>
<string>--server-url</string>
<string>http://your-panel:3000</string>
<string>--backend-id</string>
<string>1</string>
<string>--backend-token</string>
<string>ag_xxx</string>
<string>--gateway-type</string>
<string>clash</string>
<string>--gateway-url</string>
<string>http://127.0.0.1:9090</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/tmp/neko-agent-<instance>.log</string>
<key>StandardErrorPath</key>
<string>/tmp/neko-agent-<instance>.log</string>
</dict>
</plist>
Load the service:
launchctl load ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist
Unload:
launchctl unload ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist
OpenWrt — init.d
Create /etc/init.d/neko-agent:
#!/bin/sh /etc/rc.common
USE_PROCD=1
START=95
STOP=10
PROG=/usr/local/bin/neko-agent
INSTANCE=backend-1 # change as needed
CONF=/etc/neko-agent/${INSTANCE}.env
start_service() {
mkdir -p /var/run/neko-agent
# load config
[ -f "$CONF" ] && . "$CONF"
procd_open_instance
procd_set_param command "$PROG" \
--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" ] && \
procd_append_param command --gateway-token "$NEKO_GATEWAY_TOKEN"
procd_set_param respawn 3600 5 5
procd_set_param stdout 1
procd_set_param stderr 1
procd_set_param pidfile "/var/run/neko-agent/${INSTANCE}.pid"
procd_close_instance
}
Enable:
chmod +x /etc/init.d/neko-agent
/etc/init.d/neko-agent enable
/etc/init.d/neko-agent start