Skip to content
Back to search

headless

Agent skill that sets up a headless Mac, Linux or Windows machine over SSH, step by step, without ever seeing the admin password.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kunchenguid/headless with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kunchenguid/headless'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunchenguid--headless/badge.svg)](/listings/kunchenguid--headless)

HTML

<a href="/listings/kunchenguid--headless"><img src="/api/listings/kunchenguid--headless/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# install (global recommended)
$ npx skills add kunchenguid/headless -g

# in your agent
/headless set up my Mac mini at 192.168.1.20 as a headless machine

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 208 lines
  1. <h1 align="center">/headless</h1>
  2. <p align="center">
  3. <a href="https://agentskills.io"
  4. ><img
  5. alt="Agent Skills"
  6. src="https://img.shields.io/badge/Agent%20Skills-package-blue?style=flat-square"
  7. /></a>
  8. <a href="LICENSE"
  9. ><img
  10. alt="License"
  11. src="https://img.shields.io/badge/license-MIT-green?style=flat-square"
  12. /></a>
  13. <a href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
  14. ><img
  15. alt="Platform"
  16. src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
  17. /></a>
  18. <a href="https://x.com/kunchenguid"
  19. ><img
  20. alt="X"
  21. src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
  22. /></a>
  23. <a href="https://discord.gg/Wsy2NpnZDu"
  24. ><img
  25. alt="Discord"
  26. src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
  27. /></a>
  28. </p>
  29. <h3 align="center">What if a new machine set itself up while you watched?</h3>
  30. A Mac mini in a closet, a Linux box under the desk, a Windows PC nobody sits
  31. at. Making one run unattended means a dozen settings at the console - never
  32. sleep, sign in by itself after a restart, SSH keys only - and then, usually,
  33. handing your agent the admin password so it can do the rest.
  34. **headless** is an [Agent Skill](https://agentskills.io) that takes a machine
  35. from "an admin account with a password and remote login on" to a configured
  36. headless machine over SSH, one step at a time: it never sleeps, signs itself
  37. in after a restart, takes SSH keys only, and optionally joins Tailscale. The
  38. admin password stays in your secret store; the agent only ever names the
  39. entry.
  40. - **The password never reaches the agent** - it stays in Automic Vault,
  41. 1Password, Bitwarden, any command, or, as a last resort, a private env file.
  42. The scripts read it and pipe it on; it never lands on a command line or in a
  43. log.
  44. - **Mac, Linux and Windows** - Apple silicon Macs with
  45. [Determinate Nix](https://determinate.systems) and
  46. [nix-darwin](https://github.com/nix-darwin/nix-darwin); NixOS with this
  47. repository's NixOS module, any other distribution replaced with NixOS by
  48. [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) if you
  49. choose, or Debian, Ubuntu and Fedora kept with a distro-neutral script;
  50. Windows 11 and Windows Server 2025 with a rerunnable PowerShell script over
  51. OpenSSH.
  52. - **Every step reruns safely** - each step says what it does, runs, and shows
  53. its result; the last step reads every setting back, restarts the machine
  54. and checks it comes back.
  55. - **Proven end to end** - each platform's whole journey runs on a
  56. GitHub-hosted runner over SSH to itself, and the logs are checked for the
  57. password.
  58. ## Quick Start
  59. ```sh
  60. # install (global recommended)
  61. $ npx skills add kunchenguid/headless -g
  62. # in your agent
  63. /headless set up my Mac mini at 192.168.1.20 as a headless machine
  64. ```
  65. ## What it needs
  66. - **Your computer:** macOS or Linux with bash, ssh and tar (and Nix, only to
  67. install NixOS on a Linux machine).
  68. - **The machine:** an Apple silicon Mac on a current macOS, an x86_64 or
  69. aarch64 Linux machine with systemd, or a Windows 11 or Windows Server 2025
  70. PC - with an admin account that has a password, and remote login on.
  71. - **A secret store** for that password. Tailscale is optional.
  72. ## How It Works
  73. For a Mac the skill walks you through seven steps:
  74. ```
  75. admin account + password + Remote Login on
  76. │
  77. ▼
  78. ┌────────────────────┐
  79. │ admin access │ you, once, at the Mac
  80. └─────────┬──────────┘
  81. ▼
  82. ┌────────────────────┐
  83. │ save the password │ you, once, in your secret store
  84. └─────────┬──────────┘
  85. ▼
  86. ┌────────────────────┐
  87. │ config folder │ on your computer, from this repository's default config
  88. └─────────┬──────────┘
  89. ▼
  90. ┌────────────────────┐
  91. │ first SSH sign-in │ host key pinned · your key added
  92. └─────────┬──────────┘
  93. ▼
  94. ┌────────────────────┐
  95. │ admin session │ Determinate Nix · FileVault off · automatic sign-in
  96. └─────────┬──────────┘
  97. ▼
  98. ┌────────────────────┐
  99. │ apply │ the config · Tailscale if you want it
  100. └─────────┬──────────┘
  101. ▼
  102. ┌────────────────────┐
  103. │ verify + restart │ every setting read back · the Mac comes back
  104. └─────────┬──────────┘
  105. ▼
  106. headless Mac
  107. ```
  108. A Linux machine takes the same path, without the admin session: after the
  109. first sign-in, a machine on NixOS is applied as it is; on another
  110. distribution you choose between installing NixOS (the whole disk is erased)
  111. and keeping it with the script.
  112. A Windows PC starts with a few lines you paste in an administrator
  113. PowerShell to turn OpenSSH Server on (and, on a home or office network
  114. Windows calls Public, to mark it Private so SSH gets through the firewall).
  115. After the first sign-in, applying the config sets key-only SSH, automatic
  116. sign-in (the password kept as an LSA secret), the extras and Tailscale.
  117. ## Usage
  118. | Invoke | Example |
  119. | ------ | ------- |
  120. | Slash | `/headless set up my Mac mini at 192.168.1.20 as a headless machine` |
  121. | Natural language | "update my headless Linux server and check it comes back after a restart" |
  122. The agent should auto-invoke when asked to set up, configure, update or check
  123. a machine you reach only over SSH.
  124. ## Package layout
  125. ```
  126. skills/headless/
  127. SKILL.md # the agent contract: the rules and every step
  128. references/ # mac.md · linux.md · windows.md · secrets.md · tailscale.md
  129. scripts/ # mac/ · linux/ · windows/: connect, apply, verify, restart, tailscale
  130. assets/ # darwin/ · nixos/ · windows/: the default configs the skill copies
  131. modules/
  132. darwin/headless.nix # the nix-darwin module, darwinModules.headless
  133. nixos/headless.nix # the NixOS module, nixosModules.headless
  134. flake.nix # the modules, templates.darwin (default) and templates.nixos
  135. tests/ # the secret helper's test and the Mac, Linux and Windows journeys CI runs
  136. ```
  137. Ships as an [`npx skills`](https://github.com/vercel-labs/skills) package.
  138. The repository is also a Nix flake, and the modules are the layers the skill
  139. applies. Use them from your own flake:
  140. ```nix
  141. inputs.headless.url = "github:kunchenguid/headless";
  142. # in your darwinSystem modules:
  143. headless.darwinModules.headless
  144. { headless = { user = "admin"; sshKeys = [ "ssh-ed25519 ..." ]; }; }
  145. ```
  146. `nixosModules.headless` is used the same way in a `nixosSystem`. The options
  147. are listed in `skills/headless/references/mac.md` and
  148. `skills/headless/references/linux.md`.
  149. `nix flake init -t github:kunchenguid/headless#nixos` (or `#darwin`) gives the
  150. starting config the skill copies, the NixOS one with a disko disk layout for
  151. new installs.
  152. ## Development
  153. ```sh
  154. # edit the skill
  155. $EDITOR skills/headless/SKILL.md
  156. # smoke-test discovery locally
  157. npx skills add ./ -l
  158. # install from this checkout
  159. npx skills add ./ -g -y
  160. # checks
  161. nix flake check # modules and default configs build (this system's)
  162. tests/secret-run.test.sh # the password is piped, never printed
  163. shellcheck -x tests/*.sh skills/headless/scripts/*.sh skills/headless/scripts/*/*.sh skills/headless/scripts/*/remote/*.sh
  164. ```
  165. The `mac` workflow runs the whole journey on a GitHub-hosted Mac, over SSH
  166. to itself. The `linux` workflow runs the distro-neutral script on a
  167. GitHub-hosted Ubuntu runner over SSH to itself, and installs NixOS with
  168. nixos-anywhere on an x86_64 Ubuntu virtual machine there, then applies,
  169. restarts and verifies it. The `windows` workflow checks every PowerShell
  170. file parses, then runs the Windows journey on a GitHub-hosted Windows Server
  171. runner over SSH to itself, from Ubuntu under WSL. Each checks its log never
  172. holds the password.
  173. Pull requests to `main` are raised through
  174. [no-mistakes](https://github.com/kunchenguid/no-mistakes): the
  175. `PR must be raised via no-mistakes` check stays red on a pull request opened
  176. by hand until its branch is pushed through the gate (`git push no-mistakes`),
  177. which writes a pipeline attestation into the pull request's description.
skills/headless/scripts/windows/remote/apply.ps1 · Bundled script · 200 lines · 1 finding marked
  1. # apply.ps1 - make the Windows machine what settings.json says, changing
  2. # only what differs; run by apply.sh in the administrator's SSH session. It
  3. # prints one "headless: changed: ..." line per change, and none when run
  4. # again with the same settings.
  5. #
  6. # usage: apply.ps1 -Login ACCOUNT
  7. # With autoLogin on, the account's password is the first line of standard
  8. # input; it is checked against the account, kept only as the LSA secret
  9. # Windows' automatic sign-in reads, and never printed.
  10. param([Parameter(Mandatory = $true)][string]$Login)
  11. . (Join-Path $PSScriptRoot 'common.ps1')
  12. function Changed([string]$What) { [Console]::Out.WriteLine("headless: changed: $What") }
  13. # Set-Reg KEY NAME TYPE VALUE WHAT: set a registry value unless it already
  14. # holds VALUE; say WHAT when it changed.
  15. function Set-Reg([string]$Key, [string]$Name, [string]$Type, $Value, [string]$What) {
  16. if (-not (Test-Path $Key)) { New-Item -Path $Key -Force | Out-Null }
  17. $have = Get-RegValue $Key $Name
  18. $kind = $null
  19. if ($null -ne $have) { $kind = (Get-Item $Key).GetValueKind($Name).ToString() }
  20. if ($null -ne $have -and "$have" -eq "$Value" -and $kind -eq $Type) { return }
  21. if ($null -ne $have -and $kind -ne $Type) { Remove-ItemProperty -Path $Key -Name $Name }
  22. New-ItemProperty -Path $Key -Name $Name -PropertyType $Type -Value $Value -Force | Out-Null
  23. Changed $What
  24. }
  25. function Remove-Reg([string]$Key, [string]$Name, [string]$What) {
  26. if ($null -eq (Get-RegValue $Key $Name)) { return }
  27. Remove-ItemProperty -Path $Key -Name $Name
  28. Changed $What
  29. }
  30. # Set-Power SUBGROUP SETTING VALUE WHAT: on AC and on battery, in the active
  31. # power plan.
  32. function Set-Power([string]$Sub, [string]$Setting, [long]$Value, [string]$What) {
  33. $ac = [Headless.Native]::ReadPower($Sub, $Setting, $true)
  34. $dc = [Headless.Native]::ReadPower($Sub, $Setting, $false)
  35. if ($ac -eq -1) { return }
  36. if ($ac -eq $Value -and ($dc -eq $Value -or $dc -eq -1)) { return }
  37. powercfg /setacvalueindex SCHEME_CURRENT $Sub $Setting $Value
  38. if ($LASTEXITCODE -ne 0) { Fail "powercfg could not set $What" }
  39. powercfg /setdcvalueindex SCHEME_CURRENT $Sub $Setting $Value
  40. powercfg /setactive SCHEME_CURRENT
  41. Changed $What
  42. }
  43. $me = [Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()
  44. if (-not $me.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { Fail "$Login's SSH session has no administrator rights" }
  45. if ($env:USERNAME -ne $Login) { Fail "signed in as $env:USERNAME, not $Login" }
  46. $s = Read-Settings (Join-Path $HeadlessHome 'config\settings.json') $Login
  47. $password = $null
  48. if ($s.autoLogin) {
  49. $password = [Console]::In.ReadLine()
  50. if ([string]::IsNullOrEmpty($password)) { Fail 'automatic sign-in is on, but no password came on standard input' }
  51. # Checked before anything changes, so a wrong password changes nothing.
  52. if (-not (Get-LocalUser -Name $Login -ErrorAction SilentlyContinue)) {
  53. Fail "$Login is not a local account here; automatic sign-in needs a local account"
  54. }
  55. if (-not [Headless.Native]::CheckPassword($Login, $password)) {
  56. Fail "the password in the store does not sign $Login in on this machine; nothing was changed"
  57. }
  58. }
  59. # --- Host name (Windows takes a new name at the next restart).
  60. $names = Get-ComputerNames
  61. if ($s.hostName -and $s.hostName -ne $names.Pending) {
  62. Rename-Computer -NewName $s.hostName -Force -WarningAction SilentlyContinue
  63. Changed "host name $($s.hostName) (from the next restart)"
  64. $names = Get-ComputerNames
  65. }
  66. # --- Automatic sign-in: Winlogon signs the account in at start-up with the
  67. # password kept as the LSA secret DefaultPassword (never the plain-text
  68. # registry value of the same name).
  69. if ($s.autoLogin) {
  70. Set-Reg $Winlogon 'DefaultUserName' 'String' $Login "automatic sign-in account $Login"
  71. Set-Reg $Winlogon 'DefaultDomainName' 'String' $names.Pending "automatic sign-in domain $($names.Pending) (this computer)"
  72. Remove-Reg $Winlogon 'DefaultPassword' 'plain-text DefaultPassword removed from the registry'
  73. Remove-Reg $Winlogon 'AutoLogonCount' 'automatic sign-in no longer stops after a count'
  74. if (-not [Headless.Native]::SecretIs('DefaultPassword', $password)) {
  75. [Headless.Native]::SetSecret('DefaultPassword', $password)
  76. Changed 'automatic sign-in password, kept as an LSA secret'
  77. }
  78. Set-Reg $Winlogon 'AutoAdminLogon' 'String' '1' 'automatic sign-in on'
  79. # "Only allow Windows Hello sign-in" turns automatic sign-in off.
  80. if ($null -ne (Get-RegValue $PasswordLess 'DevicePasswordLessBuildVersion')) {
  81. Set-Reg $PasswordLess 'DevicePasswordLessBuildVersion' 'DWord' 0 'Windows Hello-only sign-in off (it blocks automatic sign-in)'
  82. }
  83. } else {
  84. if ((Get-RegValue $Winlogon 'AutoAdminLogon') -eq '1') {
  85. Set-Reg $Winlogon 'AutoAdminLogon' 'String' '0' 'automatic sign-in off'
  86. }
  87. Remove-Reg $Winlogon 'DefaultPassword' 'plain-text DefaultPassword removed from the registry'
  88. if ([Headless.Native]::HasSecret('DefaultPassword')) {
  89. [Headless.Native]::RemoveSecret('DefaultPassword')
  90. Changed 'automatic sign-in password removed from the LSA secrets'
  91. }
  92. }
  93. $password = $null
  94. # --- Extras. An extra turned off is no longer managed: its setting stays
  95. # as it is.
  96. $x = $s.extras
  97. if ($x.neverSleep) {
  98. if ((Get-RegValue $PowerKey 'HibernateEnabled') -ne 0) {
  99. powercfg /hibernate off
  100. if ($LASTEXITCODE -ne 0) { Fail 'powercfg could not turn hibernation off' }
  101. Changed 'hibernation off (and with it fast start-up)'
  102. }
  103. Set-Power $SubSleep $StandbyIdle 0 'sleep after: never'
  104. Set-Power $SubSleep $HibernateIdle 0 'hibernate after: never'
  105. }
  106. if ($x.powerButtonShutsDown) {
  107. Set-Power $SubButtons $PowerButtonAction 3 'power button: shut down'
  108. }
  109. if ($x.hideSleep) {
  110. Set-Reg $Flyout 'ShowSleepOption' 'DWord' 0 'Sleep hidden from the power menu'
  111. }
  112. if ($x.updatesOvernight) {
  113. Set-Reg $UpdateUx 'SmartActiveHoursState' 'DWord' 0 'Windows Update active hours set by hand'
  114. Set-Reg $UpdateUx 'ActiveHoursStart' 'DWord' $ActiveHoursStart "Windows Update active hours from ${ActiveHoursStart}:00"
  115. Set-Reg $UpdateUx 'ActiveHoursEnd' 'DWord' $ActiveHoursEnd "Windows Update active hours to ${ActiveHoursEnd}:00"
  116. }
  117. # --- Tailscale: Tailscale's own Windows installer, in unattended mode (it
  118. # runs before anyone signs in). An existing install is kept, and gets the
  119. # same unattended policy the installer would set.
  120. if ($s.tailscale.enable) {
  121. if (-not (Test-Path $TailscaleExe)) {
  122. $arch = @{ AMD64 = 'amd64'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]
  123. if (-not $arch) { Fail "no Tailscale installer for $env:PROCESSOR_ARCHITECTURE" }
  124. $msi = Join-Path $HeadlessHome "tailscale-setup-$TailscaleVersion-$arch.msi"
  125. [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
  126. Invoke-WebRequest -UseBasicParsing -Uri "https://pkgs.tailscale.com/stable/tailscale-setup-$TailscaleVersion-$arch.msi" -OutFile $msi
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 135 on GitHub
  127. if ((Get-FileHash -Algorithm SHA256 $msi).Hash.ToLower() -ne $TailscaleSha256[$arch]) {
  128. Remove-Item $msi
  129. Fail 'the Tailscale installer did not match its pinned SHA-256; nothing was installed'
  130. }
  131. $p = Start-Process -FilePath msiexec.exe -Wait -PassThru -ArgumentList '/i', "`"$msi`"", '/quiet', '/norestart', 'TS_UNATTENDEDMODE=always', 'TS_NOLAUNCH=true'
  132. Remove-Item $msi
  133. if ($p.ExitCode -ne 0 -and $p.ExitCode -ne 3010) { Fail "the Tailscale installer failed (exit code $($p.ExitCode))" }
  134. Changed "Tailscale $TailscaleVersion installed, unattended"
  135. }
  136. Set-Reg 'HKLM:\SOFTWARE\Policies\Tailscale' 'UnattendedMode' 'String' 'always' 'Tailscale runs unattended (before anyone signs in)'
  137. $svc = Get-Service -Name Tailscale -ErrorAction SilentlyContinue
  138. if (-not $svc) { Fail 'Tailscale is installed but has no Tailscale service' }
  139. if ($svc.StartType -ne 'Automatic') { Set-Service -Name Tailscale -StartupType Automatic; Changed 'Tailscale service starts at start-up' }
  140. if ($svc.Status -ne 'Running') { Start-Service -Name Tailscale; Changed 'Tailscale service started' }
  141. }
  142. # --- SSH: your keys, PowerShell as the SSH shell, key-only sign-in.
  143. if (-not (Test-Path $AdminKeys)) { New-Item -ItemType File -Path $AdminKeys | Out-Null }
  144. $have = @(Get-Content $AdminKeys)
  145. foreach ($k in $s.sshKeys) {
  146. if ($have -notcontains $k) { Add-Content -Path $AdminKeys -Value $k -Encoding Ascii; Changed "SSH key added: $(($k -split ' ')[0]) ...$($k.Substring([Math]::Max(0, $k.Length - 24)))" }
  147. }
  148. if (-not (Test-AdminOnlyAcl $AdminKeys)) {
  149. icacls $AdminKeys /inheritance:r /grant:r "*${SidAdministrators}:F" "*${SidSystem}:F" | Out-Null
  150. if ($LASTEXITCODE -ne 0) { Fail 'could not limit administrators_authorized_keys to Administrators and SYSTEM' }
  151. Changed 'administrators_authorized_keys readable by Administrators and SYSTEM only'
  152. }
  153. Set-Reg 'HKLM:\SOFTWARE\OpenSSH' 'DefaultShell' 'String' $PowerShellExe 'SSH shell: Windows PowerShell'
  154. $sshd = Get-CimInstance Win32_Service -Filter "Name='sshd'"
  155. if (-not $sshd) { Fail 'OpenSSH Server (sshd) is not installed' }
  156. if ($sshd.StartMode -ne 'Auto') { Set-Service -Name sshd -StartupType Automatic; Changed 'OpenSSH Server starts at start-up' }
  157. $sshdExe = ($sshd.PathName -replace '^"([^"]+)".*$', '$1') -replace '^(\S+\.exe).*$', '$1'
  158. # The machine's record of its settings, which verify.ps1 checks against.
  159. New-Item -ItemType Directory -Force -Path $HeadlessHome | Out-Null
  160. $record = Join-Path $HeadlessHome 'settings.json'
  161. $json = $s | ConvertTo-Json -Depth 4
  162. if (-not (Test-Path $record) -or [IO.File]::ReadAllText($record) -ne $json) {
  163. [IO.File]::WriteAllText($record, $json)
  164. }
  165. $text = ''
  166. if (Test-Path $SshdConfig) { $text = [IO.File]::ReadAllText($SshdConfig) }
  167. $parts = Split-SshdConfig $text
  168. $block = Get-SshdBlock $s
  169. if (($parts.Block -join "`n") -ne ($block -join "`n")) {
  170. $new = (@($block) + @($parts.Rest)) -join "`r`n"
  171. $candidate = "$SshdConfig.headless-new"
  172. [IO.File]::WriteAllText($candidate, $new)
  173. $t = Invoke-Sshd $sshdExe @('-t', '-f', "`"$candidate`"")
  174. if (-not $t.Ok) {
  175. Remove-Item $candidate
  176. Fail "sshd rejected the new sshd_config, which was not changed: $($t.Err)"
  177. }
  178. if (-not (Test-Path "$SshdConfig.before-headless") -and (Test-Path $SshdConfig)) {
  179. Copy-Item $SshdConfig "$SshdConfig.before-headless"
  180. }
  181. Move-Item -Force $candidate $SshdConfig
  182. if ($s.keyOnlySsh) { Changed 'SSH: key sign-in only, password sign-in off' } else { Changed 'SSH: password sign-in left as sshd_config says' }
  183. # Restarting sshd keeps sessions that are open, this one included.
  184. Restart-Service -Name sshd -Force
  185. } elseif ((Get-Service sshd).Status -ne 'Running') {
  186. Start-Service -Name sshd
  187. Changed 'OpenSSH Server started'
  188. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.