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.
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
Markdown
[](/listings/kunchenguid--headless)HTML
<a href="/listings/kunchenguid--headless"><img src="/api/listings/kunchenguid--headless/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- <h1 align="center">/headless</h1>
- <p align="center">
- <a href="https://agentskills.io"
- ><img
- alt="Agent Skills"
- src="https://img.shields.io/badge/Agent%20Skills-package-blue?style=flat-square"
- /></a>
- <a href="LICENSE"
- ><img
- alt="License"
- src="https://img.shields.io/badge/license-MIT-green?style=flat-square"
- /></a>
- <a href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
- ><img
- alt="Platform"
- src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"
- /></a>
- <a href="https://x.com/kunchenguid"
- ><img
- alt="X"
- src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
- /></a>
- <a href="https://discord.gg/Wsy2NpnZDu"
- ><img
- alt="Discord"
- src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
- /></a>
- </p>
- <h3 align="center">What if a new machine set itself up while you watched?</h3>
- A Mac mini in a closet, a Linux box under the desk, a Windows PC nobody sits
- at. Making one run unattended means a dozen settings at the console - never
- sleep, sign in by itself after a restart, SSH keys only - and then, usually,
- handing your agent the admin password so it can do the rest.
- **headless** is an [Agent Skill](https://agentskills.io) that takes a machine
- from "an admin account with a password and remote login on" to a configured
- headless machine over SSH, one step at a time: it never sleeps, signs itself
- in after a restart, takes SSH keys only, and optionally joins Tailscale. The
- admin password stays in your secret store; the agent only ever names the
- entry.
- - **The password never reaches the agent** - it stays in Automic Vault,
- 1Password, Bitwarden, any command, or, as a last resort, a private env file.
- The scripts read it and pipe it on; it never lands on a command line or in a
- log.
- - **Mac, Linux and Windows** - Apple silicon Macs with
- [Determinate Nix](https://determinate.systems) and
- [nix-darwin](https://github.com/nix-darwin/nix-darwin); NixOS with this
- repository's NixOS module, any other distribution replaced with NixOS by
- [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) if you
- choose, or Debian, Ubuntu and Fedora kept with a distro-neutral script;
- Windows 11 and Windows Server 2025 with a rerunnable PowerShell script over
- OpenSSH.
- - **Every step reruns safely** - each step says what it does, runs, and shows
- its result; the last step reads every setting back, restarts the machine
- and checks it comes back.
- - **Proven end to end** - each platform's whole journey runs on a
- GitHub-hosted runner over SSH to itself, and the logs are checked for the
- password.
- ## Quick Start
- ```sh
- # 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 it needs
- - **Your computer:** macOS or Linux with bash, ssh and tar (and Nix, only to
- install NixOS on a Linux machine).
- - **The machine:** an Apple silicon Mac on a current macOS, an x86_64 or
- aarch64 Linux machine with systemd, or a Windows 11 or Windows Server 2025
- PC - with an admin account that has a password, and remote login on.
- - **A secret store** for that password. Tailscale is optional.
- ## How It Works
- For a Mac the skill walks you through seven steps:
- ```
- admin account + password + Remote Login on
- │
- ▼
- ┌────────────────────┐
- │ admin access │ you, once, at the Mac
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ save the password │ you, once, in your secret store
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ config folder │ on your computer, from this repository's default config
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ first SSH sign-in │ host key pinned · your key added
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ admin session │ Determinate Nix · FileVault off · automatic sign-in
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ apply │ the config · Tailscale if you want it
- └─────────┬──────────┘
- ▼
- ┌────────────────────┐
- │ verify + restart │ every setting read back · the Mac comes back
- └─────────┬──────────┘
- ▼
- headless Mac
- ```
- A Linux machine takes the same path, without the admin session: after the
- first sign-in, a machine on NixOS is applied as it is; on another
- distribution you choose between installing NixOS (the whole disk is erased)
- and keeping it with the script.
- A Windows PC starts with a few lines you paste in an administrator
- PowerShell to turn OpenSSH Server on (and, on a home or office network
- Windows calls Public, to mark it Private so SSH gets through the firewall).
- After the first sign-in, applying the config sets key-only SSH, automatic
- sign-in (the password kept as an LSA secret), the extras and Tailscale.
- ## Usage
- | Invoke | Example |
- | ------ | ------- |
- | Slash | `/headless set up my Mac mini at 192.168.1.20 as a headless machine` |
- | Natural language | "update my headless Linux server and check it comes back after a restart" |
- The agent should auto-invoke when asked to set up, configure, update or check
- a machine you reach only over SSH.
- ## Package layout
- ```
- skills/headless/
- SKILL.md # the agent contract: the rules and every step
- references/ # mac.md · linux.md · windows.md · secrets.md · tailscale.md
- scripts/ # mac/ · linux/ · windows/: connect, apply, verify, restart, tailscale
- assets/ # darwin/ · nixos/ · windows/: the default configs the skill copies
- modules/
- darwin/headless.nix # the nix-darwin module, darwinModules.headless
- nixos/headless.nix # the NixOS module, nixosModules.headless
- flake.nix # the modules, templates.darwin (default) and templates.nixos
- tests/ # the secret helper's test and the Mac, Linux and Windows journeys CI runs
- ```
- Ships as an [`npx skills`](https://github.com/vercel-labs/skills) package.
- The repository is also a Nix flake, and the modules are the layers the skill
- applies. Use them from your own flake:
- ```nix
- inputs.headless.url = "github:kunchenguid/headless";
- # in your darwinSystem modules:
- headless.darwinModules.headless
- { headless = { user = "admin"; sshKeys = [ "ssh-ed25519 ..." ]; }; }
- ```
- `nixosModules.headless` is used the same way in a `nixosSystem`. The options
- are listed in `skills/headless/references/mac.md` and
- `skills/headless/references/linux.md`.
- `nix flake init -t github:kunchenguid/headless#nixos` (or `#darwin`) gives the
- starting config the skill copies, the NixOS one with a disko disk layout for
- new installs.
- ## Development
- ```sh
- # edit the skill
- $EDITOR skills/headless/SKILL.md
- # smoke-test discovery locally
- npx skills add ./ -l
- # install from this checkout
- npx skills add ./ -g -y
- # checks
- nix flake check # modules and default configs build (this system's)
- tests/secret-run.test.sh # the password is piped, never printed
- shellcheck -x tests/*.sh skills/headless/scripts/*.sh skills/headless/scripts/*/*.sh skills/headless/scripts/*/remote/*.sh
- ```
- The `mac` workflow runs the whole journey on a GitHub-hosted Mac, over SSH
- to itself. The `linux` workflow runs the distro-neutral script on a
- GitHub-hosted Ubuntu runner over SSH to itself, and installs NixOS with
- nixos-anywhere on an x86_64 Ubuntu virtual machine there, then applies,
- restarts and verifies it. The `windows` workflow checks every PowerShell
- file parses, then runs the Windows journey on a GitHub-hosted Windows Server
- runner over SSH to itself, from Ubuntu under WSL. Each checks its log never
- holds the password.
- Pull requests to `main` are raised through
- [no-mistakes](https://github.com/kunchenguid/no-mistakes): the
- `PR must be raised via no-mistakes` check stays red on a pull request opened
- by hand until its branch is pushed through the gate (`git push no-mistakes`),
- 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
- # apply.ps1 - make the Windows machine what settings.json says, changing
- # only what differs; run by apply.sh in the administrator's SSH session. It
- # prints one "headless: changed: ..." line per change, and none when run
- # again with the same settings.
- #
- # usage: apply.ps1 -Login ACCOUNT
- # With autoLogin on, the account's password is the first line of standard
- # input; it is checked against the account, kept only as the LSA secret
- # Windows' automatic sign-in reads, and never printed.
- param([Parameter(Mandatory = $true)][string]$Login)
- . (Join-Path $PSScriptRoot 'common.ps1')
- function Changed([string]$What) { [Console]::Out.WriteLine("headless: changed: $What") }
- # Set-Reg KEY NAME TYPE VALUE WHAT: set a registry value unless it already
- # holds VALUE; say WHAT when it changed.
- function Set-Reg([string]$Key, [string]$Name, [string]$Type, $Value, [string]$What) {
- if (-not (Test-Path $Key)) { New-Item -Path $Key -Force | Out-Null }
- $have = Get-RegValue $Key $Name
- $kind = $null
- if ($null -ne $have) { $kind = (Get-Item $Key).GetValueKind($Name).ToString() }
- if ($null -ne $have -and "$have" -eq "$Value" -and $kind -eq $Type) { return }
- if ($null -ne $have -and $kind -ne $Type) { Remove-ItemProperty -Path $Key -Name $Name }
- New-ItemProperty -Path $Key -Name $Name -PropertyType $Type -Value $Value -Force | Out-Null
- Changed $What
- }
- function Remove-Reg([string]$Key, [string]$Name, [string]$What) {
- if ($null -eq (Get-RegValue $Key $Name)) { return }
- Remove-ItemProperty -Path $Key -Name $Name
- Changed $What
- }
- # Set-Power SUBGROUP SETTING VALUE WHAT: on AC and on battery, in the active
- # power plan.
- function Set-Power([string]$Sub, [string]$Setting, [long]$Value, [string]$What) {
- $ac = [Headless.Native]::ReadPower($Sub, $Setting, $true)
- $dc = [Headless.Native]::ReadPower($Sub, $Setting, $false)
- if ($ac -eq -1) { return }
- if ($ac -eq $Value -and ($dc -eq $Value -or $dc -eq -1)) { return }
- powercfg /setacvalueindex SCHEME_CURRENT $Sub $Setting $Value
- if ($LASTEXITCODE -ne 0) { Fail "powercfg could not set $What" }
- powercfg /setdcvalueindex SCHEME_CURRENT $Sub $Setting $Value
- powercfg /setactive SCHEME_CURRENT
- Changed $What
- }
- $me = [Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()
- if (-not $me.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { Fail "$Login's SSH session has no administrator rights" }
- if ($env:USERNAME -ne $Login) { Fail "signed in as $env:USERNAME, not $Login" }
- $s = Read-Settings (Join-Path $HeadlessHome 'config\settings.json') $Login
- $password = $null
- if ($s.autoLogin) {
- $password = [Console]::In.ReadLine()
- if ([string]::IsNullOrEmpty($password)) { Fail 'automatic sign-in is on, but no password came on standard input' }
- # Checked before anything changes, so a wrong password changes nothing.
- if (-not (Get-LocalUser -Name $Login -ErrorAction SilentlyContinue)) {
- Fail "$Login is not a local account here; automatic sign-in needs a local account"
- }
- if (-not [Headless.Native]::CheckPassword($Login, $password)) {
- Fail "the password in the store does not sign $Login in on this machine; nothing was changed"
- }
- }
- # --- Host name (Windows takes a new name at the next restart).
- $names = Get-ComputerNames
- if ($s.hostName -and $s.hostName -ne $names.Pending) {
- Rename-Computer -NewName $s.hostName -Force -WarningAction SilentlyContinue
- Changed "host name $($s.hostName) (from the next restart)"
- $names = Get-ComputerNames
- }
- # --- Automatic sign-in: Winlogon signs the account in at start-up with the
- # password kept as the LSA secret DefaultPassword (never the plain-text
- # registry value of the same name).
- if ($s.autoLogin) {
- Set-Reg $Winlogon 'DefaultUserName' 'String' $Login "automatic sign-in account $Login"
- Set-Reg $Winlogon 'DefaultDomainName' 'String' $names.Pending "automatic sign-in domain $($names.Pending) (this computer)"
- Remove-Reg $Winlogon 'DefaultPassword' 'plain-text DefaultPassword removed from the registry'
- Remove-Reg $Winlogon 'AutoLogonCount' 'automatic sign-in no longer stops after a count'
- if (-not [Headless.Native]::SecretIs('DefaultPassword', $password)) {
- [Headless.Native]::SetSecret('DefaultPassword', $password)
- Changed 'automatic sign-in password, kept as an LSA secret'
- }
- Set-Reg $Winlogon 'AutoAdminLogon' 'String' '1' 'automatic sign-in on'
- # "Only allow Windows Hello sign-in" turns automatic sign-in off.
- if ($null -ne (Get-RegValue $PasswordLess 'DevicePasswordLessBuildVersion')) {
- Set-Reg $PasswordLess 'DevicePasswordLessBuildVersion' 'DWord' 0 'Windows Hello-only sign-in off (it blocks automatic sign-in)'
- }
- } else {
- if ((Get-RegValue $Winlogon 'AutoAdminLogon') -eq '1') {
- Set-Reg $Winlogon 'AutoAdminLogon' 'String' '0' 'automatic sign-in off'
- }
- Remove-Reg $Winlogon 'DefaultPassword' 'plain-text DefaultPassword removed from the registry'
- if ([Headless.Native]::HasSecret('DefaultPassword')) {
- [Headless.Native]::RemoveSecret('DefaultPassword')
- Changed 'automatic sign-in password removed from the LSA secrets'
- }
- }
- $password = $null
- # --- Extras. An extra turned off is no longer managed: its setting stays
- # as it is.
- $x = $s.extras
- if ($x.neverSleep) {
- if ((Get-RegValue $PowerKey 'HibernateEnabled') -ne 0) {
- powercfg /hibernate off
- if ($LASTEXITCODE -ne 0) { Fail 'powercfg could not turn hibernation off' }
- Changed 'hibernation off (and with it fast start-up)'
- }
- Set-Power $SubSleep $StandbyIdle 0 'sleep after: never'
- Set-Power $SubSleep $HibernateIdle 0 'hibernate after: never'
- }
- if ($x.powerButtonShutsDown) {
- Set-Power $SubButtons $PowerButtonAction 3 'power button: shut down'
- }
- if ($x.hideSleep) {
- Set-Reg $Flyout 'ShowSleepOption' 'DWord' 0 'Sleep hidden from the power menu'
- }
- if ($x.updatesOvernight) {
- Set-Reg $UpdateUx 'SmartActiveHoursState' 'DWord' 0 'Windows Update active hours set by hand'
- Set-Reg $UpdateUx 'ActiveHoursStart' 'DWord' $ActiveHoursStart "Windows Update active hours from ${ActiveHoursStart}:00"
- Set-Reg $UpdateUx 'ActiveHoursEnd' 'DWord' $ActiveHoursEnd "Windows Update active hours to ${ActiveHoursEnd}:00"
- }
- # --- Tailscale: Tailscale's own Windows installer, in unattended mode (it
- # runs before anyone signs in). An existing install is kept, and gets the
- # same unattended policy the installer would set.
- if ($s.tailscale.enable) {
- if (-not (Test-Path $TailscaleExe)) {
- $arch = @{ AMD64 = 'amd64'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]
- if (-not $arch) { Fail "no Tailscale installer for $env:PROCESSOR_ARCHITECTURE" }
- $msi = Join-Path $HeadlessHome "tailscale-setup-$TailscaleVersion-$arch.msi"
- [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
- 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
- if ((Get-FileHash -Algorithm SHA256 $msi).Hash.ToLower() -ne $TailscaleSha256[$arch]) {
- Remove-Item $msi
- Fail 'the Tailscale installer did not match its pinned SHA-256; nothing was installed'
- }
- $p = Start-Process -FilePath msiexec.exe -Wait -PassThru -ArgumentList '/i', "`"$msi`"", '/quiet', '/norestart', 'TS_UNATTENDEDMODE=always', 'TS_NOLAUNCH=true'
- Remove-Item $msi
- if ($p.ExitCode -ne 0 -and $p.ExitCode -ne 3010) { Fail "the Tailscale installer failed (exit code $($p.ExitCode))" }
- Changed "Tailscale $TailscaleVersion installed, unattended"
- }
- Set-Reg 'HKLM:\SOFTWARE\Policies\Tailscale' 'UnattendedMode' 'String' 'always' 'Tailscale runs unattended (before anyone signs in)'
- $svc = Get-Service -Name Tailscale -ErrorAction SilentlyContinue
- if (-not $svc) { Fail 'Tailscale is installed but has no Tailscale service' }
- if ($svc.StartType -ne 'Automatic') { Set-Service -Name Tailscale -StartupType Automatic; Changed 'Tailscale service starts at start-up' }
- if ($svc.Status -ne 'Running') { Start-Service -Name Tailscale; Changed 'Tailscale service started' }
- }
- # --- SSH: your keys, PowerShell as the SSH shell, key-only sign-in.
- if (-not (Test-Path $AdminKeys)) { New-Item -ItemType File -Path $AdminKeys | Out-Null }
- $have = @(Get-Content $AdminKeys)
- foreach ($k in $s.sshKeys) {
- 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)))" }
- }
- if (-not (Test-AdminOnlyAcl $AdminKeys)) {
- icacls $AdminKeys /inheritance:r /grant:r "*${SidAdministrators}:F" "*${SidSystem}:F" | Out-Null
- if ($LASTEXITCODE -ne 0) { Fail 'could not limit administrators_authorized_keys to Administrators and SYSTEM' }
- Changed 'administrators_authorized_keys readable by Administrators and SYSTEM only'
- }
- Set-Reg 'HKLM:\SOFTWARE\OpenSSH' 'DefaultShell' 'String' $PowerShellExe 'SSH shell: Windows PowerShell'
- $sshd = Get-CimInstance Win32_Service -Filter "Name='sshd'"
- if (-not $sshd) { Fail 'OpenSSH Server (sshd) is not installed' }
- if ($sshd.StartMode -ne 'Auto') { Set-Service -Name sshd -StartupType Automatic; Changed 'OpenSSH Server starts at start-up' }
- $sshdExe = ($sshd.PathName -replace '^"([^"]+)".*$', '$1') -replace '^(\S+\.exe).*$', '$1'
- # The machine's record of its settings, which verify.ps1 checks against.
- New-Item -ItemType Directory -Force -Path $HeadlessHome | Out-Null
- $record = Join-Path $HeadlessHome 'settings.json'
- $json = $s | ConvertTo-Json -Depth 4
- if (-not (Test-Path $record) -or [IO.File]::ReadAllText($record) -ne $json) {
- [IO.File]::WriteAllText($record, $json)
- }
- $text = ''
- if (Test-Path $SshdConfig) { $text = [IO.File]::ReadAllText($SshdConfig) }
- $parts = Split-SshdConfig $text
- $block = Get-SshdBlock $s
- if (($parts.Block -join "`n") -ne ($block -join "`n")) {
- $new = (@($block) + @($parts.Rest)) -join "`r`n"
- $candidate = "$SshdConfig.headless-new"
- [IO.File]::WriteAllText($candidate, $new)
- $t = Invoke-Sshd $sshdExe @('-t', '-f', "`"$candidate`"")
- if (-not $t.Ok) {
- Remove-Item $candidate
- Fail "sshd rejected the new sshd_config, which was not changed: $($t.Err)"
- }
- if (-not (Test-Path "$SshdConfig.before-headless") -and (Test-Path $SshdConfig)) {
- Copy-Item $SshdConfig "$SshdConfig.before-headless"
- }
- Move-Item -Force $candidate $SshdConfig
- if ($s.keyOnlySsh) { Changed 'SSH: key sign-in only, password sign-in off' } else { Changed 'SSH: password sign-in left as sshd_config says' }
- # Restarting sshd keeps sessions that are open, this one included.
- Restart-Service -Name sshd -Force
- } elseif ((Get-Service sshd).Status -ne 'Running') {
- Start-Service -Name sshd
- Changed 'OpenSSH Server started'
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.