Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
An open source, self-hosted implementation of the Tailscale control server.
| Port | 8080 |
| Registry | ghcr.io/daemonless/headscale |
| Source | https://github.com/juanfont/headscale |
| Website | https://headscale.net/ |
| Tag | Description | Best For |
|---|---|---|
| latest | Built from the official upstream FreeBSD release binary. | Most users — recommended. |
| pkg | Installed from the FreeBSD quarterly package repository. | Alternative build. |
| pkg-latest | Installed from the FreeBSD latest package repository. | Alternative build. |
Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions.
services:
headscale:
image: "ghcr.io/daemonless/headscale:latest"
container_name: headscale
environment:
- PUID=1000 # User ID for the application process
- PGID=1000 # Group ID for the application process
- TZ=UTC # Timezone for the container
volumes:
- "/path/to/containers/headscale:/config"
ports:
- "8080:8080"
- "3478:3478"
restart: unless-stopped.env:
# .env DIRECTOR_PROJECT=headscale PUID=1000 PGID=1000 TZ=UTC
appjail-director.yml:
# appjail-director.yml
options:
- virtualnet: ':<random> default'
- nat:
services:
headscale:
name: headscale
options:
- container: 'boot args:--pull'
- expose: '8080:8080 proto:tcp'
- expose: '3478:3478 proto:udp'
oci:
user: root
environment:
- PUID: !ENV '${PUID}'
- PGID: !ENV '${PGID}'
- TZ: !ENV '${TZ}'
volumes:
- headscale: /config
volumes:
headscale:
device: '/path/to/containers/headscale'Makejail:
# Makejail
ARG tag=latest
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/headscale:${tag}
Note: Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the IPv4 address assigned by the virtual network.
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:latestappjail oci run -Pd \
-o overwrite=force \
-o container="args:--pull" \
-o virtualnet=":<random> default" \
-o nat \
-o expose="8080:8080 proto:tcp" \
-o expose="3478:3478 proto:udp" \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=UTC \
-o fstab="/path/to/containers/headscale /config <pseudofs>" \
ghcr.io/daemonless/headscale:latest headscaleNote: Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the IPv4 address assigned by the virtual network.
- 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"Access at: http://localhost:8080
| 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 |
| Path | Description |
|---|---|
| /config | Configuration directory |
| 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
Need help? Join our Discord community.