<!doctype html><htmllang=enclass=no-js><head><metacharset=utf-8><metaname=viewportcontent="width=device-width,initial-scale=1"><metaname=descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaname=authorcontent="Headscale authors"><linkhref=https://juanfont.github.io/headscale/development/usage/getting-started/rel=canonical><linkhref=../../setup/upgrade/rel=prev><linkhref=../connect/android/rel=next><linkrel=iconhref=../../assets/favicon.png><metaname=generatorcontent="mkdocs-1.6.1, mkdocs-material-9.5.48"><title>Getting started - Headscale</title><linkrel=stylesheethref=../../assets/stylesheets/main.6f8fc17f.min.css><linkrel=stylesheethref=../../assets/stylesheets/palette.06af60db.min.css><linkrel=preconnecthref=https://fonts.gstatic.comcrossorigin><linkrel=stylesheethref="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"><style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style><script>__md_scope=newURL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script><metaproperty=og:typecontent=website><metaproperty=og:titlecontent="Getting started - Headscale"><metaproperty=og:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaproperty=og:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/usage/getting-started.png><metaproperty=og:image:typecontent=image/png><metaproperty=og:image:widthcontent=1200><metaproperty=og:image:heightcontent=630><metacontent=https://juanfont.github.io/headscale/development/usage/getting-started/property=og:url><metaname=twitter:cardcontent=summary_large_image><metaname=twitter:titlecontent="Getting started - Headscale"><metaname=twitter:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaname=twitter:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/usage/getting-started.png></head><bodydir=ltrdata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigo><inputclass=md-toggledata-md-toggle=drawertype=checkboxid=__drawerautocomplete=off><inputclass=md-toggledata-md-toggle=searchtype=checkboxid=__searchautocomplete=off><labelclass=md-overlayfor=__drawer></label><divdata-md-component=skip><ahref=#getting-startedclass=md-skip> Skip to content </a></div><divdata-md-component=announce></div><divdata-md-color-scheme=defaultdata-md-component=outdatedhidden></div><headerclass=md-headerdata-md-component=header><navclass="md-header__inner md-grid"aria-label=Header><ahref=../..title=Headscaleclass="md-header__button md-logo"aria-label=Headscaledata-md-component=logo><imgsrc=../../logo/headscale3-dots.svgalt=logo></a><labelclass="md-header__button md-icon"for=__drawer><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg></label><divclass=md-header__titledata-md-component=header-title><divclass=md-header__ellipsis><divclass=md-header__topic><spanclass=md-ellipsis> Headscale </span></div><divclass=md-header__topicdata-md-component=header-topic><spanclass=md-ellipsis> Getting started </span></div></div></div><formclass=md-header__optiondata-md-component=palette><inputclass=md-optiondata-md-color-mediadata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigoaria-label="Switch to dark mode"type=radioname=__paletteid=__palette_0><labelclass="md-header__button md-icon"title="Switch to dark mode"for=__palette_1hidden><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M128a44000-444400044440004-444000-4-4m010a6600
</span></code></pre></div></div><divclass=tabbed-block><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-1-1><aid=__codelineno-1-1name=__codelineno-1-1href=#__codelineno-1-1></a><spanclass=c1># Show help</span>
</span></code></pre></div></div></div></div><h2id=manage-users>Manage users<aclass=headerlinkhref=#manage-userstitle="Permanent link">¶</a></h2><p>In headscale, a node (also known as machine or device) is always assigned to a specific user, a <ahref=https://tailscale.com/kb/1136/tailnet/>tailnet</a>. Such users can be managed with the <code>headscale users</code> command. Invoke the built-in help for more information: <code>headscale users --help</code>.</p><h3id=create-a-user>Create a user<aclass=headerlinkhref=#create-a-usertitle="Permanent link">¶</a></h3><divclass="tabbed-set tabbed-alternate"data-tabs=2:2><inputchecked=checkedid=__tabbed_2_1name=__tabbed_2type=radio><inputid=__tabbed_2_2name=__tabbed_2type=radio><divclass=tabbed-labels><labelfor=__tabbed_2_1>Native</label><labelfor=__tabbed_2_2>Container</label></div><divclass=tabbed-content><divclass=tabbed-block><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-2-1><aid=__codelineno-2-1name=__codelineno-2-1href=#__codelineno-2-1></a>headscale<spanclass=w></span>users<spanclass=w></span>create<spanclass=w></span><USER>
</span></code></pre></div></div></div></div><h2id=register-a-node>Register a node<aclass=headerlinkhref=#register-a-nodetitle="Permanent link">¶</a></h2><p>One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect <ahref=../connect/android/>Android</a>, <ahref=../connect/apple/>Apple</a> or <ahref=../connect/windows/>Windows</a> devices.</p><h3id=normal-interactive-login>Normal, interactive login<aclass=headerlinkhref=#normal-interactive-logintitle="Permanent link">¶</a></h3><p>On a client machine, run the <code>tailscale up</code> command and provide the FQDN of your headscale instance as argument:</p><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-6-1><aid=__codelineno-6-1name=__codelineno-6-1href=#__codelineno-6-1></a>tailscale<spanclass=w></span>up<spanclass=w></span>--login-server<spanclass=w></span><YOUR_HEADSCALE_URL>
</span></code></pre></div><p>Usually, a browser window with further instructions is opened and contains the value for <code><YOUR_MACHINE_KEY></code>. Approve and register the node on your headscale server:</p><divclass="tabbed-set tabbed-alternate"data-tabs=4:2><inputchecked=checkedid=__tabbed_4_1name=__tabbed_4type=radio><inputid=__tabbed_4_2name=__tabbed_4type=radio><divclass=tabbed-labels><labelfor=__tabbed_4_1>Native</label><labelfor=__tabbed_4_2>Container</label></div><divclass=tabbed-content><divclass=tabbed-block><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-7-1><aid=__codelineno-7-1name=__codelineno-7-1href=#__codelineno-7-1></a>headscale<spanclass=w></span>nodes<spanclass=w></span>register<spanclass=w></span>--user<spanclass=w></span><USER><spanclass=w></span>--key<spanclass=w></span><YOUR_MACHINE_KEY>
</span></code></pre></div></div></div></div><h3id=using-a-preauthkey>Using a preauthkey<aclass=headerlinkhref=#using-a-preauthkeytitle="Permanent link">¶</a></h3><p>It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see <code>headscale preauthkeys --help</code> for other options):</p><divclass="tabbed-set tabbed-alternate"data-tabs=5:2><inputchecked=checkedid=__tabbed_5_1name=__tabbed_5type=radio><inputid=__tabbed_5_2name=__tabbed_5type=radio><divclass=tabbed-labels><labelfor=__tabbed_5_1>Native</label><labelfor=__tabbed_5_2>Container</label></div><divclass=tabbed-content><divclass=tabbed-block><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-9-1><aid=__codelineno-9-1name=__codelineno-9-1href=#__codelineno-9-1></a>headscale<spanclass=w></span>preauthkeys<spanclass=w></span>create<spanclass=w></span>--user<spanclass=w></span><USER>
</span></code></pre></div></div></div></div><p>The command returns the preauthkey on success which is used to connect a node to the headscale instance via the <code>tailscale up</code> command:</p><divclass="language-shell highlight"><pre><span></span><code><spanid=__span-11-1><aid=__codelineno-11-1name=__codelineno-11-1href=#__codelineno-11-1></a>tailscale<spanclass=w></span>up<spanclass=w></span>--login-server<spanclass=w></span><YOUR_HEADSCALE_URL><spanclass=w></span>--authkey<spanclass=w></span><YOUR_AUTH_KEY>
