Skip to content


headscale logo

Version: 0.13.1 Type: application AppVersion: 0.22.3

An open source, self-hosted implementation of the Tailscale control server.

This chart is not maintained by the upstream project and any issues with the chart should be raised here

Source Code


Kubernetes: >=1.22.0-0


Repository Name Version common 1.5.1 postgresql 14.0.5

Installing the Chart

To install the chart with the release name headscale

helm install headscale oci://


helm repo add gabe565
helm repo update
helm install headscale gabe565/headscale

Uninstalling the Chart

To uninstall the headscale deployment

helm uninstall headscale

The command removes all the Kubernetes components associated with the chart including persistent volumes and deletes the release.


Read through the values.yaml file. It has several commented out suggested values. Other values may be used from the values.yaml from the bjw-s common library.

Specify each parameter using the --set key=value[,key=value] argument to helm install.

helm install headscale \
  --set env.TZ="America/New York" \

Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart.

helm install headscale gabe565/headscale -f values.yaml

Custom configuration

Headscale runs in a distroless Docker container, which does not have any of the expected command line utilities. This keeps the container small and minimizes the possibility of CVEs, but it makes working with a config file in Kubernetes more difficult.

To keep config simple, this Helm chart suggests using environment variables. All of the Headscale config variables are supported as envs, but official documentation is lacking.

To configure Headscale:

  1. See the Headscale example config for available variables.

  2. For any that you want to set: flatten object keys using _, then prefix with HEADSCALE_.

    • For example, the following config:
      disable_check_updates: true
        level: warn
      would be set with the following Helm values:
        HEADSCALE_LOG_LEVEL: "warn"

Also, note that this chart sets some defaults based on your values. See templates/common.yaml for a list.

Headscale UI

You can deploy gurucomputing/headscale-ui as a sidecar container by adding the following values:

      - name: http
        containerPort: 80

        port: 80

    enabled: true
      - host:
          - path: /web
              port: 80
      - ...

Once deployed, the UI will be available at /web.


Important: When deploying an application Helm chart you can add more values from the bjw-s common library chart here

Key Type Default Description
args list ["headscale","serve"] Container args string nil ACL policy JSON [ref]
configMaps.acl.enabled bool false Enables ACL policy
env object See values.yaml Environment variables. [ref]
env.HEADSCALE_DNS_CONFIG_BASE_DOMAIN string "" Defines the base domain to create the hostnames for MagicDNS. base_domain must be a FQDNs, without the trailing dot. The FQDN of the hosts will be hostname.user.base_domain (e.g.,
image.pullPolicy string "IfNotPresent" image pull policy
image.repository string "" image repository
image.tag string "0.22.3" image tag
ingress.main object See values.yaml Enable and configure ingress settings for the chart under this key.
persistence.config object See values.yaml Configure persistence settings for the chart under this key.
postgresql object See values.yaml Enable and configure postgresql database subchart under this key. For more options see postgresql chart documentation
service.main object See values.yaml Configures service settings for the chart.
serviceMonitor.main.enabled bool false Enables or disables the serviceMonitor.
serviceMonitor.main.endpoints list See values.yaml Configures the endpoints for the serviceMonitor.

Autogenerated from chart metadata using helm-docs