Skip to content

v1.0.0 — 2026-04-20

First stable release of argos-edge. The panel has walked through its full feature scope — reverse proxy, WAF, CrowdSec, 2FA, OIDC, ForwardAuth, notifications, backups, observability — plus a security-audit + test-coverage push + a full documentation portal.

Homelab-grade production-ready, solo-maintained, best-effort support.

Highlights

  • Complete edge stack in three containers. Caddy 2 + CrowdSec (LAPI + AppSec) + argos panel, ~100 MB RAM baseline, configured entirely through the panel.
  • Two deployment modes. lan (trusted network, plain HTTP panel) or behind_caddy (internet-facing, HTTPS panel under a domain you control), selected via a single env var.
  • OIDC SSO + ForwardAuth. Put any backend behind a single argos session cookie. Documented per-provider for Google, Microsoft, Keycloak, Authentik, Authelia.
  • Inline WAF with three modes. Coraza + OWASP CRS via the CrowdSec AppSec component; switch between detect / block / disabled at runtime without a restart.
  • Test-covered and security-audited. 45 test entries added across 6 packages during the v1.0 prep cycle; go vet and staticcheck both zero-warning; six security fixes landed under fix(security) commits against an internal audit report.

Installation

Docker + .env with three mandatory secrets, docker compose up -d. Two modes, full matrix in the installation guide:

Upgrade notes

Not applicable. This is the first tagged release. No prior version to migrate from.

If you ran argos from main before the tag, the path forward is the standard upgrade flow (git pull + docker compose pull up -d); schema migrations run automatically.

Breaking changes

None. First release.

Known limitations

Called out explicitly so expectations match reality:

  • No off-site backup. Backups are local tar.gz under /data/backups/ only. Replicate out of band with rclone / borg / rsync as a sidecar if you need off-site.
  • No UI user-create flow. The bootstrap admin is created once from env vars. Additional admins come through OIDC auto-provisioning or, as a break-glass, direct SQL. A POST /api/users endpoint is out of scope for v1.0.
  • No Prometheus metrics endpoint. Aggregates live behind /api/system/health JSON and the dashboard endpoints; wire to your external monitor from there.
  • No multi-tenant / roles. Every panel login is an admin with full access. Fine for a single operator; wrong shape for a team with least-privilege needs.
  • No HA. Single SQLite file, single argos process. Restart preserves DB-backed sessions but in-flight OIDC state is invalidated by design.
  • Rules do not include a rate_limit action. The five actions are forward, redirect, fixed_response, block, rewrite. Rate limiting lives at the host level under host_security, keyed by IP / header / global.
  • Docs portal screenshots are placeholders. 17 image placeholders (1x1 transparent PNGs) land with the release so mkdocs build --strict passes; real captures get replaced in follow-up commits as the maintainer produces them. Alt text on every image describes the expected content.
  • Docker images bundled with the release. Argos is distributed as source + docker-compose build; no pre-built image tags published to a registry at 1.0.0. Add to the roadmap.
  • SQLite, not Postgres. Single-writer, single-process contract. No plans to port to Postgres.

Security

Six fix(security) commits landed between the initial feature set and the tag. The ones that matter at the threat-model level:

  • affd78c — timing parity in auth.Authenticate (anti user enumeration).
  • 7bd3c28 — compare-and-swap on recovery code consumption (anti single-use race).
  • 55884b3 — X-Real-IP trust gated by panel mode (anti LAN-mode rate-limit spoof).
  • 94e3cb6 — backslash + control char rejection in safeReturnTo (anti open-redirect bypass).
  • 6858364 — opt-in email_verified enforcement on OIDC.
  • 801fa1c — remote_ip + user_agent on every auth audit event.

Plus two hygiene fixes: RateLimiter.Drop wired on channel delete (a1b7578) and PurgeTOTPAttempts wired into the retention cron (3e9186c).

Full attack-surface map and mitigation table: Threat model.

Docs portal

Goes live at https://cmos486.github.io/argos-edge/ on the first push to main that triggers the Docs GitHub Action (included in the tag). The action:

  • Runs mkdocs build --strict on every PR (no deploy).
  • Runs mkdocs gh-deploy on push to main that touches docs.

What follows v1.0

Realistic, not a promise. The next cycles are likely to focus on:

  • Pre-built Docker images published to a registry.
  • Real screenshots in the portal.
  • A POST /api/users endpoint + role tier for teams.
  • A Prometheus metrics exporter if the external-monitor path proves insufficient.
  • Authentik / Keycloak vendor scripts to cut the manual setup steps.

None of these are blockers for the v1.0 use case (single operator, homelab).

Acknowledgments

Built on excellent upstreams:

Install

git clone https://github.com/cmos486/argos-edge.git
cd argos-edge
git checkout v1.0.0
cp .env.example .env
# edit .env: ARGOS_SESSION_SECRET, ARGOS_MASTER_KEY,
# ARGOS_INITIAL_ADMIN_PASSWORD
docker compose up -d

Open http://<lan-ip>:8080, sign in with the bootstrap admin, follow the first-run checklist.