Charon

Your websites, your rules—without the headaches.

Turn multiple websites and apps into one simple dashboard. Click, save, done. No code, no config files, no PhD required.

---

Why Charon?

You want your apps accessible online. You don't want to become a networking expert first.

The problem: Managing reverse proxies usually means editing config files, memorizing cryptic syntax, and hoping you didn't break everything.

Charon's answer: A web interface where you click boxes and type domain names. That's it.

• ✅ Your blog gets a green lock (HTTPS) automatically
• ✅ Your chat server works without weird port numbers
• ✅ Your admin panel blocks everyone except you
• ✅ Everything stays up even when you make changes

---

✨ Top 10 Features

🎯 Point & Click Management

No config files. No terminal commands. Just click, type your domain name, and you're live. If you can use a website, you can run Charon.

🔐 Automatic HTTPS Certificates

Free SSL certificates that request, install, and renew themselves. Your sites get the green padlock without you lifting a finger.

🛡️ Enterprise-Grade Security Built In

Web Application Firewall, rate limiting, geographic blocking, access control lists, and intrusion detection via CrowdSec. Protection that "just works."

🔗 Smart Proxy Headers

Automatically adds standard headers (X-Real-IP, X-Forwarded-Proto, etc.) so your backend applications see real client IPs, enforce HTTPS correctly, and log accurately—with full backward compatibility for existing hosts.

🐳 Instant Docker Discovery

Already running apps in Docker? Charon finds them automatically and offers one-click proxy setup. No manual configuration required.

📊 Real-Time Monitoring & Logs

See exactly what's happening with live request logs, uptime monitoring, and instant notifications when something goes wrong.

📥 Migration Made Easy

Import your existing Caddy configurations with one click. Already invested in another reverse proxy? Bring your work with you.

⚡ Live Configuration Changes

Update domains, add security rules, or modify settings instantly—no container restarts needed.* Your sites stay up while you make changes.

🌍 Multi-App Management

Run dozens of websites, APIs, or services from a single dashboard. Perfect for homelab enthusiasts and small teams managing multiple projects.

🚀 Zero-Dependency Deployment

One Docker container. No databases to install. No external services required. No complexity—just pure simplicity.

💯 100% Free & Open Source

No premium tiers. No feature paywalls. No usage limits. Everything you see is yours to use, forever, backed by the MIT license.

^{* Note: Initial security engine setup (CrowdSec) requires a one-time container restart to initialize the protection layer. All subsequent changes happen live.}

Explore All Features →

---

Quick Start

Docker Compose (Recommended)

Save this as docker-compose.yml:

services:
  charon:
    image: ghcr.io/wikid82/charon:latest
    container_name: charon
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
      - "8080:8080"
    volumes:
      - ./charon-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - CHARON_ENV=production

Then run:

docker-compose up -d

Docker Run (One-Liner)

docker run -d \
  --name charon \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -p 8080:8080 \
  -v ./charon-data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e CHARON_ENV=production \
  ghcr.io/wikid82/charon:latest

What Just Happened?

1. Charon downloaded and started
2. The web interface opened on port 8080
3. Your websites will use ports 80 (HTTP) and 443 (HTTPS)

Open http://localhost:8080 and start adding your websites!

Upgrading? Run Migrations

If you're upgrading from a previous version with persistent data:

docker exec charon /app/charon migrate
docker restart charon

This ensures security features (especially CrowdSec) work correctly.

Important: If you had CrowdSec enabled before the upgrade, it will automatically restart after migration. You don't need to manually re-enable it via the GUI. See Migration Guide for details.

---

Getting Help

📖 Full Documentation — Everything explained simply 🚀 5-Minute Guide — Your first website up and running 💬 Ask Questions — Friendly community help 🐛 Report Problems — Something broken? Let us know

---

Authentication Flow

How Authentication Works

Charon uses a three-tier authentication system to validate user sessions:

1. Authorization Header (Authorization: Bearer <token>) — Checked first
2. HTTP Cookie (authToken) — Checked if no header present
3. Query Parameter (?token=<token>) — Fallback for WebSocket connections

Expected 401 Responses

When you first access Charon or your session expires, you'll see this in the browser console:

GET /api/auth/me → 401 Unauthorized

This is normal and expected behavior. Here's why:

• The frontend checks authentication status on page load
• If you're not logged in, the API returns 401
• The frontend receives this response and shows the login page
• Once you log in, the 401 errors disappear

Development tip: These 401 responses are not errors—they're the API's way of saying "authentication required." Modern SPAs (Single Page Applications) expect and handle these responses gracefully.

Authentication Verification

After logging in, Charon validates your session on every API request:

GET /api/auth/me → 200 OK

Response includes:

• User ID and username
• Role and permissions
• Session expiration time

Token refresh: Sessions automatically extend on activity. The default session timeout is 24 hours.

Security Considerations

• ✅ All authentication tokens use cryptographically secure random generation
• ✅ Tokens are hashed before storage in the database
• ✅ Sessions expire after inactivity
• ✅ HTTPS enforces Secure cookie attributes in production
• ✅ HttpOnly flag prevents JavaScript access to auth cookies

Learn more: See Security Features for complete authentication and authorization documentation.

---

Agent Skills

Charon uses Agent Skills for AI-discoverable, executable development tasks. Skills are self-documenting task definitions that can be executed by both humans and AI assistants like GitHub Copilot.

What are Agent Skills?

Agent Skills combine YAML metadata with Markdown documentation to create standardized, AI-discoverable task definitions. Each skill represents a specific development task (testing, building, security scanning, etc.) that can be:

• ✅ Executed directly via command line
• ✅ Discovered by AI assistants (GitHub Copilot, etc.)
• ✅ Run from VS Code tasks menu
• ✅ Integrated in CI/CD pipelines

Available Skills

Charon provides 19 operational skills across multiple categories:

• Testing (4 skills): Backend/frontend unit tests and coverage analysis
• Integration (5 skills): CrowdSec, Coraza, and full integration test suites
• Security (2 skills): Trivy vulnerability scanning and Go security checks
• QA (1 skill): Pre-commit hooks and code quality checks
• Utility (4 skills): Version management, cache clearing, database recovery
• Docker (3 skills): Development environment management

Using Skills

Command Line:

# Run backend tests with coverage
.github/skills/scripts/skill-runner.sh test-backend-coverage

# Run security scan
.github/skills/scripts/skill-runner.sh security-scan-trivy

VS Code Tasks:

1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Select Tasks: Run Task
3. Choose your skill (e.g., Test: Backend with Coverage)

GitHub Copilot: Simply ask Copilot to run tasks naturally:

• "Run backend tests with coverage"
• "Start the development environment"
• "Run security scans"

Learning More

• Agent Skills Documentation — Complete skill reference
• agentskills.io Specification — Standard format details
• Migration Guide — Transition from legacy scripts

---

Contributing

Want to help make Charon better? Check out CONTRIBUTING.md

---

MIT License · Documentation · Releases

Built with ❤️ by @Wikid82
_{Powered by Caddy Server}