https://github.com/daemonless/headscale
https://github.com/daemonless/headscale
Last synced: 12 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/daemonless/headscale
- Owner: daemonless
- Created: 2026-06-01T17:18:00.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-06-15T08:48:32.000Z (13 days ago)
- Last Synced: 2026-06-15T11:34:57.043Z (13 days ago)
- Language: Jinja
- Size: 25.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Headscale
[](https://github.com/daemonless/headscale/actions)
[](https://github.com/daemonless/headscale/commits)
An open source, self-hosted implementation of the Tailscale control server.
| | |
|---|---|
| **Port** | 8080 |
| **Registry** | `ghcr.io/daemonless/headscale` |
| **Source** | [https://github.com/juanfont/headscale](https://github.com/juanfont/headscale) |
| **Website** | [https://headscale.net/](https://headscale.net/) |
## Version Tags
| Tag | Description | Best For |
| :--- | :--- | :--- |
| `latest` | Built from the official upstream FreeBSD release binary. | Most users. Matches Linux Docker behavior. |
| `pkg` | Installed from the FreeBSD quarterly package repository. | Alternative build. |
| `pkg-latest` | Installed from the FreeBSD latest package repository. | Alternative build. |
## Prerequisites
Before deploying, ensure your host environment is ready. See the [Quick Start Guide](https://daemonless.io/guides/quick-start) for host setup instructions.
## Deployment
### Podman Compose
```yaml
services:
headscale:
image: ghcr.io/daemonless/headscale:latest
container_name: headscale
environment:
- PUID=1000
- PGID=1000
- TZ=UTC
volumes:
- "/path/to/containers/headscale:/config"
ports:
- 8080:8080
- 3478:3478
restart: unless-stopped
```
### AppJail Director
**.env**:
```
DIRECTOR_PROJECT=headscale
PUID=1000
PGID=1000
TZ=UTC
```
**appjail-director.yml**:
```yaml
options:
- virtualnet: ': default'
- nat:
services:
headscale:
name: headscale
options:
- container: 'boot args:--pull'
oci:
user: root
environment:
- PUID: !ENV '${PUID}'
- PGID: !ENV '${PGID}'
- TZ: !ENV '${TZ}'
volumes:
- headscale: /config
volumes:
headscale:
device: '/path/to/containers/headscale'
```
**Makejail**:
```
ARG tag=latest
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/headscale:${tag}
```
### Podman CLI
```bash
podman run -d --name headscale \
-p 8080:8080 \
-p 3478:3478 \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=UTC \
-v /path/to/containers/headscale:/config \
ghcr.io/daemonless/headscale:latest
```
### Ansible
```yaml
- name: Deploy headscale
containers.podman.podman_container:
name: headscale
image: ghcr.io/daemonless/headscale:latest
state: started
restart_policy: always
env:
PUID: "1000"
PGID: "1000"
TZ: "UTC"
ports:
- "8080:8080"
- "3478:3478"
volumes:
- "/path/to/containers/headscale:/config"
```
## Parameters
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PUID` | `1000` | User ID for the application process |
| `PGID` | `1000` | Group ID for the application process |
| `TZ` | `UTC` | Timezone for the container |
### Volumes
| Path | Description |
|------|-------------|
| `/config` | Configuration directory |
### Ports
| Port | Protocol | Description |
|------|----------|-------------|
| `8080` | TCP | Control server (HTTP) |
| `3478` | UDP | Embedded DERP STUN (UDP) |
**Architectures:** amd64
**User:** `bsd` (UID/GID via PUID/PGID, defaults to 1000:1000)
**Base:** FreeBSD 15.0
---
Need help? Join our [Discord](https://discord.gg/Kb9tkhecZT) community.