Skip to content

AWG Agent 1.0.0

Choose a tag to compare

View all tags
@ks-tool ks-tool released this 03 Jul 06:10
agent/v1.0.0
f91057b

The per-server daemon for Amnezia Admin: it owns the actual AmneziaWG/WireGuard interfaces on a managed server and exposes a small HTTP API (reached over an SSH tunnel or direct mTLS) that the admin app drives. Two builds, Linux only, amd64 + arm64:

  • awg-agent — kernel backend (AmneziaWG-dkms / netlink). Needs the amneziawg kernel module for obfuscated interfaces (falls back to plain WireGuard).
  • awg-agent-userspace — userspace backend with an in-process amneziawg-go device per interface: no kernel module, no netlink. Runs anywhere with /dev/net/tun, including Docker.

Features

  • Two interchangeable backends behind one API — kernel (netlink/dkms) or userspace (in-process amneziawg-go, pinned to the AmneziaWG 2.0 line). The link kind follows the "Amnezia Interface" toggle.
  • Full interface lifecycle — PUT | GET | DELETE /interfaces applies the complete device config (keys, listen port, firewall mark, AmneziaWG obfuscation params, peers) via wgctrl, with authoritative peer replacement.
  • wg-quick-style hooks — PreUp/PostUp/PreDown/PostDown (sh -c, %i → interface name) for policy routing, iptables and custom routes; Table routing encoded as explicit hooks and reconciled on in-place updates. Device-referencing PreUp hooks run after the link is up, so a tunnel's policy route applies correctly even on an agent restart.
  • Activate / deactivate toggles — a disabled interface is torn down (or never raised) with its config kept; a disabled peer is dropped from the live device but retained in config. Startup raises only active interfaces; shutdown tears active ones down.
  • Metrics — GET /metrics (CPU/RAM/load/network + per-peer rx/tx/last-handshake; JSON or Prometheus via ?fmt=prom), GET /metrics/history (up to 48h, checkpointed to disk so charts survive a restart), PATCH /metrics to toggle collection at runtime. Gone interfaces/peers are evicted eagerly and reconciled each collection tick.
  • Host capabilities — GET /info reports the backend kind, Docker availability, in-container status, kernel-module presence and creatable interface kinds.
  • Runtime profiling — GET | PATCH /profiling toggles Go runtime profiling; while on, the standard net/http/pprof endpoints are served (403 until enabled) for goroutine/heap/CPU/trace dumps.
  • IPv6 disabled on managed v4 interfaces (best-effort per-interface sysctl), so a tunnel never gets a link-local fe80:: or leaks IPv6.
  • Reachability — plain HTTP on loopback (via SSH tunnel), or mTLS on a public IP (AWG_AGENT_TLS_CERT / _KEY / _CLIENT_CA).

Running

AWG_AGENT_ADDR=127.0.0.1:8080 AWG_AGENT_DB=/var/lib/awg-agent ./awg-agent

Or deploy from the admin app (server → Deploy agent). Prerequisites: kernel build needs amneziawg-dkms; userspace needs Docker + /dev/net/tun.

Docker image (userspace agent): ghcr.io/ks-tool/awg-agent-userspace: (multi-arch amd64/arm64).

Assets 6
Loading