# 🤠 Heady
> Strategic VPN management for [Headscale](https://headscale.net) that's actually awesome to use!

<picture>
    <source
        media="(prefers-color-scheme: dark)"
        srcset="./docs/assets/preview-dark.png"
    >
    <source
        media="(prefers-color-scheme: light)"
        srcset="./docs/assets/preview-light.png"
    >
    <img
        alt="Preview"
        src="./docs/assets/preview-dark.png"
    >
</picture>

Headscale is the de-facto self-hosted version of Tailscale, a popular Wireguard
based VPN service. By default, it does not ship with a web UI, which is where
**Heady** comes in. 

**Heady** is strategic VPN management that prioritizes security, thoughtful design, and awesome user experience. Unlike feature-heavy alternatives, Heady focuses on doing the important things incredibly well.

## 🎯 What Makes Heady Different

**Security-First Design**: Every feature is evaluated for security impact first
**Convention Over Configuration**: Smart defaults that just work for 90% of setups  
**Quality Over Quantity**: Fewer features, done awesomely well
**Community-Driven**: Built for real users, not corporate feature checklists

## ✨ Awesome Features

- **Smart Machine Management**: Intuitive node administration with clear status and controls
- **Intelligent ACL Configuration**: Visual access control with tagging support  
- **Revolutionary OIDC Integration**: Zero-config role mapping that just works with any identity provider
- **DNS Made Simple**: Easy MagicDNS setup and custom record management
- **Thoughtful Configuration**: Headscale settings that make sense

## 🚀 Getting Started

**Heady** runs as a web application alongside your Headscale server. Quick setup with smart defaults gets you running fast.

### Quick Start (Docker - Recommended)
```bash
# Coming soon - simplified Docker deployment
```

### 🔧 Zero-Config OIDC Setup
Heady's revolutionary OIDC system works with any identity provider out of the box:

```yaml
oidc:
  issuer: "https://your-provider.com"
  client_id: "your-client-id" 
  client_secret: "your-secret"
  # That's it! Role mapping, scopes, and redirect URIs are auto-configured
```

Want custom roles? Easy:
```bash
HEADPLANE_ADMIN_GROUPS="admin,managers"
HEADPLANE_OWNER_GROUPS="ceo,founders"
```

## 📖 Documentation & Community

- [📋 OIDC Setup Guide](docs/OIDC-Authentication.md) - Zero-config authentication
- [🏗️ Architecture Design](GUACAMOLE_REMOTE_ACCESS_DESIGN.md) - Security-first remote access  
- [🤠 Heady Manifesto](HEADY_MANIFESTO.md) - Our philosophy and values
- [🔧 Configuration Examples](config.example.yaml) - Smart defaults you can customize

## 🎯 Deployment Options

**Heady v1.0** features a unified architecture with all awesome features available in every deployment:

- ### [Standard Deployment](/docs/Simple-Mode.md)
  Quick deployment with smart defaults. All features available, with optional integrations configured as needed.

- ### [Advanced Integration](/docs/Integrated-Mode.md)
  Enable Docker, Kubernetes, or native process integration for automatic DNS management and configuration updates.

## Versioning
Headplane uses [semantic versioning](https://semver.org/) for its releases (since v0.6.0).
Pre-release builds are available under the `next` tag and get updated when a new release
PR is opened and actively in testing.

## Contributing
Headplane is an open-source project and contributions are welcome! If you have
any suggestions, bug reports, or feature requests, please open an issue. Also
refer to the [contributor guidelines](./docs/CONTRIBUTING.md) for more info.

---

<picture>
    <source
        media="(prefers-color-scheme: dark)"
        srcset="./docs/assets/acls-dark.png"
    >
    <source
        media="(prefers-color-scheme: light)"
        srcset="./docs/assets/acls-light.png"
    >
    <img
        alt="ACLs"
        src="./docs/assets/acls-dark.png"
    >
</picture>

<picture>
    <source
        media="(prefers-color-scheme: dark)"
        srcset="./docs/assets/machine-dark.png"
    >
    <source
        media="(prefers-color-scheme: light)"
        srcset="./docs/assets/machine-light.png"
    >
    <img
        alt="Machine Management"
        src="./docs/assets/machine-dark.png"
    >
</picture>

> Copyright (c) 2025 Aarnav Tale