Skip to content

setup-system

setup-system takes a freshly installed machine to a working one: system packages, an opinionated bash configuration, ssh, git defaults, and dev tooling. It runs ephemerally via jbx — no local installation required.

jbx setup-system --dry-run     # see the whole plan, change nothing
jbx setup-system               # do it
jbx setup-system -s shell      # just the bash configuration

Every step is idempotent. Re-running setup-system is how you pick up a newer template on a machine you set up months ago, not a mistake.


Steps

Step What it does
deps Installs a baseline toolchain — C compiler, make, cmake, pkg-config, git, curl, ssh, and gpg and age for just-runit secret — then the packages of any bootstrap.toml in the current directory, both via install-deps. On a Mac without Homebrew it installs Homebrew first, which brings the Xcode Command Line Tools (the compiler and git); its installer asks for your password once.
certs Opt-in, WSL only. Installs Windows' trusted root certificates into the distro trust store beside its Mozilla bundle, one file per root, and removes any Windows no longer trusts. See below.
folders Native Windows. Moves Documents, Desktop, Pictures, Music and Videos back from OneDrive's folder redirection to the local profile, and points Windows there — as the user, no UAC. Online-only files stay on OneDrive. Elsewhere it reports skipped. See below.
shell Installs the bash configuration to ~/.config/just-bashit/ and adds one source line to ~/.bashrc and ~/.profile (and ~/.zprofile on macOS, whose login shell is zsh).
ssh Tightens permissions across ~/.ssh — repairing a directory copied from Windows, FAT, a zip or git — then creates an ed25519 key named after this host if there is no key at all. Prints the public key.
sshd macOS, opt-in: turns on Remote Login, adds github.com/<user>.keys to ~/.ssh/authorized_keys and turns password login off (below). Windows (WSL or native MSYS2 / Git Bash): a default step on native Windows, opt-in from WSL. Runs Windows' own OpenSSH server as a boot-time service — key-only, keys from github.com/<user>.keys and kept in sync with it, pwsh.exe as the login shell — so the machine answers ssh even when WSL is down, and keeps the user's WSL distro running from boot. On native Windows it also starts the ssh-agent service at boot and adds the box key to it. See below.
git Sets global git defaults that are not already set, and an unset user.name / user.email from the environment or a prompt.
tools Installs uv if missing, through install-uv: winget on Windows, which installs the native build on ARM64 (#171). Installs pre-commit hooks when the current directory is a repo with .pre-commit-config.yaml.
pwsh Installs PowerShell 7 and the PSScriptAnalyzer module, so .ps1 files can be linted on this machine. Linux and macOS only — see below.
claude Installs Claude Code if the claude command is missing: Anthropic's install.sh, or on native Windows winget, else install.ps1 (below).

On native Windows the deps baseline is CMake, Git, PowerShell 7, the GitHub CLI (gh: the sshd step authorizes the keys of the account it is signed in to), age (gpg comes with Git) and the MSVC Build Tools with two of their parts, by winget: the C++ workload (the MSVC libraries and Windows SDK clang-cl links against) and the C++ Clang Compiler for Windows component (clang-cl itself, x64 and ARM64). A Build Tools install that lacks either has it added, and one that has both is left alone (how; adding to an installed Build Tools needs admin, and under --yes it runs only from an admin shell or over the admin ssh channel, as the sshd step does). clang-cl comes from that component, not the LLVM.LLVM package, because the component's hook puts it on PATH in a Developer PowerShell for VS (or Developer Command Prompt), the shell just-makeit builds Windows in; LLVM.LLVM put it on no PATH at all (#181).

They always run in that order, whatever order you list them in — packages land before the steps that need git, curl and ssh-keygen. Every step runs by default except sshd, which opens a listening port, and certs, which widens what the machine trusts; each runs only when named with -s or in bootstrap.toml. On native Windows (MSYS2 / Git Bash) sshd is a default step too: reachability from boot is why a Windows box is being set up, and the port is key-only and scoped by --sshd-allow. Linux, macOS and WSL keep it opt-in.

jbx setup-system -s shell,ssh      # only these
jbx setup-system -x claude,deps    # everything except these

To change the default set for a project, declare it in bootstrap.toml:

[tools.setup-system]
source = "just-bashit:setup-system"
steps  = ["deps", "shell", "git"]

-s always overrides that, regardless of the toml setting.


The certs step (WSL)

On Windows Subsystem for Linux (WSL), enterprise root certificates and corporate TLS inspection proxies (such as Zscaler, Netskope, or Active Directory PKI) are installed in Windows' certificate store, but absent from the Linux distro. As a result, command-line tools (curl, git, uv, apt, Python) fail with TLS/SSL verification errors.

The certs step runs only when asked for:

jbx setup-system -s certs

It asks Windows for its trusted roots through powershell.exe:

Get-ChildItem -Path Cert:\LocalMachine\Root, Cert:\CurrentUser\Root

Each root, once, becomes its own file, jb-windows-root-<thumbprint>.crt, directly in the distro's anchor directory, and the distro's updater then merges them with its Mozilla CA bundle into the system bundle that curl, git and OpenSSL read. One certificate per file is what openssl rehash needs to link each into /etc/ssl/certs; directly in the anchor directory because p11-kit (Fedora, Arch, openSUSE) and Alpine's updater do not read subdirectories.

Distro Anchor directory Updater
Debian, Ubuntu, Alpine /usr/local/share/ca-certificates update-ca-certificates
Fedora, RHEL /etc/pki/ca-trust/source/anchors update-ca-trust extract
Arch /etc/ca-certificates/trust-source/anchors update-ca-trust extract
openSUSE /etc/pki/trust/anchors update-ca-certificates

The store is picked by which anchor directory exists, not by which updater is on PATH.

Re-running the step is how a change on Windows reaches WSL. A root Windows no longer exports is removed, so a dropped corporate root does not stay trusted; files in the anchor directory without the jb-windows-root- prefix are never touched. When nothing has changed it writes nothing and needs no sudo. If the updater fails, the roots installed before the run are put back, so the next run retries.

The step is skipped, with the reason in the summary, off WSL, on a distro none of these rows matches, and when powershell.exe cannot be found.

On WSL the bash profile also sets SSL_CERT_FILE to the system bundle when it is unset, so a tool that ships its own bundle, such as uv, sees these roots too. Off WSL it leaves SSL_CERT_FILE alone.


The folders step (native Windows)

OneDrive's Known Folder Move points Documents, Desktop, Pictures, Music and Videos at the OneDrive folder, and uninstalling OneDrive does not point them back. Documents is where PowerShell keeps $PROFILE, so a box left that way can end up with a profile that is an online-only placeholder nothing can read (#202). The folders step undoes the redirect, and is on by default:

jbx setup-system -s folders -n   # which folders are on OneDrive, and what would move
jbx setup-system -x folders      # everything else, folders left alone

The work is windows-folders.ps1, run in Windows PowerShell as you. It writes only HKCU, so it needs no UAC prompt. For each of Personal (Documents), Desktop, My Pictures, My Music and My Video under HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders whose path is inside a OneDrive folder, it:

  1. creates %USERPROFILE%\<Folder>;
  2. moves the files there with robocopy /E /MOVE, excluding online-only files (/XA:O, and by name any marked recall-on-access). Opening a cloud-only file would download it, so none is opened. A file whose name the local folder already has is not moved either, so neither copy is overwritten;
  3. sets the value, and any other value in the key that names the same folder (Documents has a second one, {F42EE2D3-…}), to %USERPROFILE%\<Folder> as REG_EXPAND_SZ;
  4. reports per folder how many files moved, how many online-only files stayed on OneDrive (download them from onedrive.com), and how many could not move;
  5. when Documents moved and get-jb.ps1 installed jbx for PowerShell, writes the jbx block into the restored Documents' profiles with get-jb.ps1's own writer.

Sign out and back in afterwards so every app sees the new paths; restarting Explorer is enough for Explorer. A folder that is already local is reported ok (local), so a re-run changes nothing.

When OneDrive would put the redirect back, nothing is moved and OneDrive is not uninstalled; that is your call. This is the case when OneDrive is running, or a Known Folder Move policy (KFMSilentOptIn or KFMBlockOptOut under HKLM:\SOFTWARE\Policies\Microsoft\OneDrive) is set. The step says so and fixes PowerShell anyway. The jbx block goes in the local Documents' profiles, and each $PROFILE Windows still reads from OneDrive gets a stub in the block's place that dot-sources its local twin. Your own lines in that profile are kept. A profile that cannot be read, such as an online-only placeholder, is never written: it is named in the summary instead. Quit OneDrive (or stop its folder backup) and clear the policy, then jbx setup-system -s folders moves the folders.

With JB_PS_PROFILE set (you named your own profile), the step moves the folders but leaves every profile alone. From WSL the step reports skipped: run it from Windows, through jbx in PowerShell or from Git Bash.


The shell step

Your ~/.bashrc is yours. The shell step never rewrites it — it installs two files of its own and appends one line that sources each:

~/.config/just-bashit/
    bashrc.sh      interactive settings — readline, history, aliases, prompt
    profile.sh     environment — PATH, EDITOR, ssh-agent
    bashrc.d/      your additions; sourced last, never overwritten
# appended to ~/.bashrc
if [ -r "$HOME/.config/just-bashit/bashrc.sh" ]; then . "$HOME/.config/just-bashit/bashrc.sh"; fi

# appended to ~/.profile (and ~/.bash_profile, when that file exists)
if [ -r "$HOME/.config/just-bashit/profile.sh" ]; then . "$HOME/.config/just-bashit/profile.sh"; fi

zsh reads neither ~/.profile nor ~/.bash_profile, and it is the login shell on macOS, so there the profile.sh line also goes in ~/.zprofile (elsewhere only when that file already exists). profile.sh is POSIX sh, which zsh sources as it is; bashrc.sh is bash's own and is not offered to zsh. profile.sh also puts Homebrew on PATH — /opt/homebrew on Apple silicon, /usr/local on Intel — behind your own ~/bin and ~/.local/bin.

Uninstalling is deleting those lines. Re-running with a newer just-bashit replaces bashrc.sh and profile.sh in place, keeping the copy it replaced as bashrc.sh.bak.

Why two files

Every distro's stock ~/.bashrc opens with an interactive-only guard:

case $- in *i*) ;; *) return;; esac

Anything exported below that line reaches interactive terminals and nothing else. ~/.profile runs once per login session, and everything descended from that session inherits its exports — scripts, language servers, agents, GUI apps — whether or not a terminal was involved. A PATH or SSH_AUTH_SOCK set only in .bashrc therefore works when you type it and is missing from anything that did not come from a terminal.

So environment lives in profile.sh, read by login shells, and interactive settings live in bashrc.sh. Because terminal emulators start non-login shells that never read ~/.profile, bashrc.sh sources profile.sh itself when no login shell has already done so. Both paths converge; neither duplicates the other.

profile.sh is written in POSIX sh, not bash, because ~/.profile is also read by dash and by desktop session managers.

Put your own settings in bashrc.d/

~/.config/just-bashit/bashrc.d/*.sh is sourced last, so anything there wins over the template and survives the next setup-system run.

What you get

Arrow keys search history. Type ssh and press Up: you get your last ssh command, not your last command. Each key is bound in both normal (\e[A) and application (\eOA) cursor modes, so it works in tmux and screen as well as a bare terminal.

An ssh-agent that already has your keys. profile.sh adopts an inherited agent if there is one — forwarded, systemd socket-activated, gnome-keyring, 1Password — and only starts its own if nothing is listening, on a fixed socket path so the next login reuses it instead of leaking an agent per shell. bashrc.sh then adds any ~/.ssh/NAME that has a matching NAME.pub and is not already loaded, which is why passphrase prompts happen once per key per boot rather than once per terminal.

History that survives. 100 000 entries, deduplicated, timestamped, appended rather than overwritten, and flushed at every prompt — closing one terminal never discards what another one recorded.

A prompt worth the columns. [✗2] ~/code/project (main*) $ — exit status only after a failure, user@host only when the session is remote or containerised, git branch from symbolic-ref and a tracked-file diff rather than git status, which stalls the prompt in large repos.

Plus: colour ls/grep/diff probed rather than assumed (GNU takes --color=auto, BSD takes -G), ll/la/../..., mkcd, interactive guards on rm/cp/mv, bash 4 shell options behind a version check so macOS's bash 3.2 does not error, and bash-completion loaded from whichever of five paths this distro or Homebrew prefix uses.

Opt-outs

Set any of these in ~/.bashrc before the source line:

Variable Effect
JB_SSH_AGENT=0 Do not start or adopt an ssh-agent
JB_SSH_AUTOADD=0 Agent yes, but do not add ~/.ssh keys to it
JB_PATH=0 Leave PATH alone
JB_PROMPT=0 Leave PS1 alone
JB_PROMPT_GIT=0 Prompt without the git branch
JB_PROMPT_COLOR=0 Prompt without colour
JB_READLINE=0 No key bindings
JB_ALIASES=0 No aliases
JB_SAFE_ALIASES=0 Aliases, but no interactive rm/cp/mv guards
JB_COMPLETION=0 Do not load bash-completion

The ssh step

Creates a key only when ~/.ssh holds no private key with a matching .pub — a machine that already has an identity does not get another one. The key is ed25519, named after the host, and the public half is printed with the gh command to register it:

jbx setup-system -s ssh
# generating ed25519 key /home/you/.ssh/workstation
# ...
# gh ssh-key add /home/you/.ssh/workstation.pub --title 'workstation'

--key-name NAME overrides the filename.

On macOS the step first pins the host's name. A Mac with no HostName set takes its name from the network it is on (mac-mini.lan one hour, Matthews-Mac-mini.local the next), so a key named after it, and ssh's %l, stop agreeing. When HostName is unset the step sets it to the lowercased LocalHostName (sudo scutil --set HostName matthews-mac-mini), the name Tailscale gives the node too; a HostName already set is left alone. It then points github.com at the key in ~/.ssh/config, between # >>> just-bashit markers: zsh, a Mac's login shell, never reads bashrc.sh, so no shell would put the key in the agent and git over ssh would find nothing to offer. Any of ssh's default keys (id_ed25519 and the rest) that exist are listed after it, since naming a key for a host stops ssh trying the defaults there. A Host github.com entry of your own, a symlinked ~/.ssh/config and markers that do not pair are left as they are, and nothing is added.

On native Windows that key also goes into Windows' own ssh-agent service, the one pwsh, Windows' ssh.exe, Git and VS Code all use — the bash ssh-agent the shell step starts is one none of them sees. The sshd step does it, since its elevated run is what turns the service on; see the ssh agent on Windows.

Repairing a ~/.ssh that lost its permissions

The step also tightens permissions on everything already in ~/.ssh, before it considers generating anything — so it doubles as the repair for a directory that arrived from somewhere unable to carry POSIX modes. Run it on its own:

jbx setup-system -s ssh

First, check whether you need it at all. A Linux-to-Linux copy loses nothing if the transport carries modes, and then no repair is required:

rsync -a  ~/.ssh/  newhost:~/.ssh/           # -a preserves permissions
tar cf - ~/.ssh | ssh newhost 'tar xf -'     # tar stores them too

Modes cannot survive a crossing that has nowhere to record them, and no choice of copy command changes that:

Crossing Why it loses them
Windows filesystem under WSL (/mnt/c/…) DrvFs has no POSIX modes; files read as 0777
FAT / exFAT stick the filesystem has no mode bits
zip modes are optional and routinely dropped
a git repo git records only the exec bit

Those are the cases this step is for. ssh refuses a key it considers readable by anyone else, with UNPROTECTED PRIVATE KEY FILE and no hint as to the fix.

What it does, and deliberately does not do:

Target Action
~/.ssh and any subdirectory owner gets rwx, group and other lose everything
a private key, found by its -----BEGIN … PRIVATE KEY----- header group and other lose everything
config, authorized_keys, authorized_keys2 group and other lose everything
*.pub left alone — public by definition
anything else, known_hosts included left alone

A key is recognised by that header rather than by its name, so one with no matching .pub, or not called id_*, is still repaired.

It only ever tightens

The sweep removes group and other bits and never adds owner bits, so a key deliberately kept at 0400 stays 0400 instead of gaining owner-write. Running it twice changes nothing the second time, and --dry-run changes nothing at all.

No effect on Windows / MSYS2

MSYS2 on NTFS does not honour chmod, so the sweep is a no-op there — it neither helps nor harms. Windows OpenSSH reads ACLs rather than mode bits, and repairing those needs icacls, which this step does not do.

That is what ssh-to-windows is for: it publishes WSL2's keys to %USERPROFILE%\.ssh and sets the ACLs Windows OpenSSH requires.

The suite states this rather than hiding it: the permission tests probe whether chmod sticks and skip on the Windows runner, where they would otherwise assert nothing while reporting green. They run for real on Linux and macOS.

--yes creates the key with an empty passphrase

Without --yes, ssh-keygen prompts for a passphrase as usual. With --yes there is nothing to prompt on, so the key is written unprotected — appropriate for a throwaway VM or a container, not for a laptop.


The git step

Sets these only when the key has no value already, so nothing you have chosen is overwritten:

Key Value
init.defaultBranch main
pull.rebase true
rebase.autoStash true
push.default simple
push.autoSetupRemote true
fetch.prune true
diff.colorMoved zebra
color.ui auto
core.editor $EDITOR
core.sshCommand native Windows only: Windows' ssh.exe (why)

Then user.name and user.email, again only when unset globally:

  1. from GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL when those are exported;
  2. otherwise asked for, when stdin is a terminal and --yes was not given (an empty answer skips it);
  3. otherwise a warning naming the command to run — never a guessed value.

A per-repo git config user.email ... still overrides the global value wherever one is set.

GIT_AUTHOR_NAME="Ada" GIT_AUTHOR_EMAIL="ada@example.com" jbx setup-system -s git

The pwsh step

Installs a native PowerShell 7 and the PSScriptAnalyzer module, which is what make lint-psscriptanalyzer needs to check a repo's .ps1 files. That target fails loudly when the module is absent, deliberately: an analyzer that never ran has checked nothing.

On Linux it installs a pinned release tarball:

/opt/microsoft/powershell/7/pwsh     the unpacked release
/usr/bin/pwsh                        the symlink that puts it on PATH

The architecture is derived from uname -m — x86_64 → x64, aarch64 or arm64 → arm64, armv7l → arm32 — because these machines are not all x86. A hardcoded x64 URL fails on an arm box inside tar, with a message naming neither the architecture nor the download.

The version is pinned in the script, so picking up a newer PowerShell is an upgrade you chose rather than whatever was released this morning. Re-running the step after a bump replaces the tree in place.

On macOS it installs Microsoft's osx tarball at the same pin, linked as /usr/local/bin/pwsh (macOS keeps /usr/bin read-only). The Linux tarball would produce a pwsh that cannot execute there, and Homebrew no longer has a powershell cask.

On Windows it does nothing but say so, and reports skipped rather than pretending otherwise. install-deps has a winget section, but this step does not use it yet — that is #59 — so for now install PowerShell there with winget install Microsoft.PowerShell.

A machine that already has pwsh on PATH keeps it; only the module install runs, and that is skipped too when Get-Module -ListAvailable already finds it. Install-Module runs with -Scope CurrentUser, so it needs no elevation. The tarball install does, and uses sudo only when you are not already root — a root container needs neither the flag nor the package.

Under WSL this is also what removes the path-translation problem: with a native interpreter present, Linux paths are handed to pwsh untouched instead of being rewritten with wslpath -w for pwsh.exe.


The sshd step

An ssh server inside WSL2 — or Tailscale SSH running there — dies with the WSL VM, and the VM stops on its own when it is idle or after a crash. So the machine is unreachable at exactly the moments you most need to reach it. Windows' own sshd is a service: it starts at boot, before anyone logs in, whether or not WSL ever does. From there wsl is one command away.

On native Windows a plain jbx setup-system includes it; from WSL it runs only when asked for:

jbx setup-system -s sshd --github-user octocat
jbx setup-system -s sshd --github-user octocat \
    --sshd-allow 100.64.0.0/10,fd7a:115c:a1e0::/48   # a Tailscale tailnet only

The work is done by windows-sshd.ps1, which must run elevated. Only a box's first run needs anyone at the desktop. The step copies the script to the Windows %TEMP% and then takes the first of these that applies (one ladder, win-admin-route in windows.sh, which the deps step's Visual Studio modify takes too):

  • Already elevated — run from an admin PowerShell, or a Git Bash started from one: it runs the script directly, with no UAC prompt. Only this step runs elevated because you are; the rest of the run writes your files as usual.
  • With an admin ssh channel — every run after the first: it runs the script over ssh to this machine's own sshd, from WSL. An admin logged in by key gets an elevated session with no UAC prompt, so this works from anywhere, including a session you reached the box through remotely, and the output streams back live. The channel is win-admin-channel in windows.sh, which proves the far end is this machine and elevated before it is trusted.
  • With --yes, and neither: it never raises a prompt. The step is reported skipped (needs admin -- re-run from an admin PowerShell), so an unattended run cannot sit on a hidden UAC prompt.
  • Otherwise — the first run: it raises one UAC prompt on the Windows desktop, waits, and relays the script's log. Declining the prompt is reported as a failure, not a success.

The dry run says which of these it would use. Relaunching the whole run elevated is deliberately not one of them: files it created in your profile would be owned by Administrators, which git's safe.directory check and the ~/.ssh permissions both refuse. The script can also be run on its own from an elevated PowerShell — Get-Help .\windows-sshd.ps1 -Full documents it. Every part is idempotent: re-running is how new keys arrive.

What it does, in order:

Keys Mirrors github.com/<user>.keys — where the ssh step already tells you to register each machine's key — into the file sshd reads for you: administrators_authorized_keys for a local admin (sshd ignores an admin's ~/.ssh/authorized_keys), ~/.ssh/authorized_keys otherwise. The keys sit inside a marked block, so keys you add by hand outside it survive, and the ACL is reset every run. No keys, no run: with passwords off and nothing authorized, the server would admit nobody.
Server Installs the OpenSSH.Server capability if it is missing. InstallPending (Windows finishes it at the next reboot) counts as installed. When it is missing and Windows is waiting on a reboot to finish servicing (Component Based Servicing's RebootPending or RebootInProgress), the run stops before changing anything and the summary says so: reboot Windows, then re-run setup-system -s sshd. Windows Update's RebootRequired and PendingFileRenameOperations do not block it and are not counted.
Auth Sets PasswordAuthentication no and PubkeyAuthentication yes in the global section of sshd_config, above the first Match (below it, a setting applies only to that match). Validated with sshd -t; rejected, the previous file is restored.
Shell pwsh.exe as the login shell, installed when missing at the pinned version — the same one the pwsh step installs on Linux — with winget, or the release MSI in the one context winget refuses (a first run elevated through UAC). The MSI matches the machine's architecture, which is read from the registry because an emulated x64 parent process reports x64.
Firewall Limits the port-22 rule to --sshd-allow (any admits every address). Without it, an existing rule keeps the addresses it admits, so a re-run never widens a tailnet-only rule (#219), and a new rule admits any address, and adds jb-sshd-wsl, a rule admitting this machine's own WSL by its virtual interface, which is what the admin ssh channel above connects through. Windows pins that rule to the adapter's GUID and WSL rebuilds the adapter with a new one on every boot, so a SYSTEM task, \just-bashit\jb-sshd-wsl-rescope, re-scopes it each time WSL's switch comes up (and at startup). The task runs a copy of the script in %ProgramData%\just-bashit, writable only by administrators.
Service Starts at boot (Automatic), restarted so the new configuration is live.
Key refresh With --github-user, a SYSTEM task, \just-bashit\jb-sshd-key-refresh, re-reads github.com/<user>.keys at startup and every 4 hours and rewrites the marked block. A machine whose key reaches GitHub after this box was set up is then let in with no visit here (#215). A fetch that fails or returns no key changes nothing, so a GitHub outage cannot lock the box.
WSL keep-alive When the user has a WSL distro, the task \just-bashit\jb-wsl-keepalive runs wsl.exe --exec /bin/sleep infinity as that user from boot (S4U: no logon needed), and again every 5 minutes if it has died. WSL stops a distro once nothing on Windows holds it open, which takes down tailscaled and any service inside it, such as a CI runner.
Agent Native Windows only (-SshAgent): the OpenSSH Authentication Agent service (ssh-agent), which Windows ships Disabled, is set to Automatic and started. In the same elevated run, so still at most one prompt. Where the OpenSSH client capability is absent, it is a note and nothing changes.

After a reboot, check from WSL that jb-sshd-wsl follows the adapter WSL built this boot, and that ssh to the Windows sshd connects:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File 'C:\ProgramData\just-bashit\windows-sshd.ps1' -CheckWslRule; jbx just-bashit:windows win-admin-channel && echo 'ssh: connects' || echo 'ssh: FAILED'

The first half prints jb-sshd-wsl scope: current ({guid}) when the rule names the live vEthernet (WSL...) adapter's GUID, or STALE, MISSING or no WSL adapter; it reads the firewall's own store, so it needs no elevation. The second half prints the admin channel (user@host) and ssh: connects, or ssh: FAILED.

It runs the same from WSL and from native Windows (MSYS2 or Git Bash): the only difference is whether a Windows path is translated with wslpath or cygpath. Nothing is quoted across a process boundary — the elevated body is written to run.ps1 beside the script and powershell.exe is handed only -File launch.ps1 — so no iconv or base64 is needed on either.

--github-user defaults to the account gh is signed in to. On Linux the step reports skipped; enable the distro's own sshd unit instead.

On macOS

macOS's own OpenSSH server is Remote Login; launchd starts sshd for each connection, so there is no service to keep alive. -s sshd does three things, each left alone when it is already so:

  1. Adds github.com/<user>.keys to ~/.ssh/authorized_keys, keeping any key already there. Nothing re-reads them later; re-running the step is the refresh.
  2. Turns Remote Login on (sudo systemsetup -setremotelogin on). macOS allows that only from a terminal with Full Disk Access, so the step reads the state back afterwards; if it is still off it says so, and the switch is System Settings > General > Sharing > Remote Login.
  3. Turns password and keyboard-interactive login off, with /etc/ssh/sshd_config.d/050-just-bashit.conf — named to sort before macOS's own 100-macos.conf, since sshd keeps the first value it reads. Only when authorized_keys has a key, so it cannot lock you out; the file is checked with sshd -t and removed again if sshd rejects it. Deleting it turns passwords back on.
jbx setup-system -s sshd --github-user octocat

--sshd-allow has no macOS meaning — its firewall filters by application, not by address — and is reported and ignored.

The ssh agent on native Windows

After the elevated run, as you rather than as an administrator, the step adds the box key (~/.ssh/<host>, or --key-name) to the Windows ssh-agent service with Windows' own C:\Windows\System32\OpenSSH\ssh-add.exe. The service keeps keys across reboots, so this happens once per box; a later run finds the key listed and reports agent: ok (... already in the Windows agent). It runs whatever became of the server half, so an agent started by an earlier run still gets the key. A key with a passphrase is added at a terminal, where ssh-add asks for it once; under --yes, or with no terminal, it is never prompted for — the summary reports agent: skipped (passphrase key: run ssh-add '...') with the command to run from PowerShell. With the service not running (the elevated run was skipped or declined) the summary says so and nothing is added.

The git step then points git at the client that talks to that agent: core.sshCommand = C:/Windows/System32/OpenSSH/ssh.exe (forward slashes, since git hands the value to a shell), so Git for Windows, pwsh and VS Code share the one agent rather than Git's bundled MSYS ssh, which reaches none. Only the global value is read: the Git for Windows installer can set core.sshCommand in the system gitconfig (C:\Program Files\Git\etc\gitconfig), and that does not stop it. A global value you already set is kept, and the summary says so (git: ok (...; core.sshCommand kept: <value>)); with no ssh.exe at that path nothing is set and the summary says core.sshCommand not set: no C:/Windows/System32/OpenSSH/ssh.exe. To check it from PowerShell:

Get-Service ssh-agent | Select-Object Status, StartType; ssh-add -l; git config --global core.sshCommand

Expect Running Automatic, your key's fingerprint, and C:/Windows/System32/OpenSSH/ssh.exe.

Windows' PATH may be absent from WSL (appendWindowsPath=false); the step then finds powershell.exe and cmd.exe under Windows\System32 of wherever the mount table says C: is mounted.


Options

Flag Long form Description
-h --help Show help and exit
-n --dry-run Print the plan; change nothing
-v --verbose Print extra detail
-y --yes Never prompt: the ssh key gets an empty passphrase (see the ssh warning above), and on Windows no UAC prompt is raised -- a step that needs admin runs directly in an admin shell or over the admin ssh channel, and is skipped otherwise (sshd)
-s STEPS --steps STEPS Comma-separated steps to run
-x STEPS --skip STEPS Comma-separated steps to leave out
--prefix DIR Config directory (default ~/.config/just-bashit)
--key-name NAME ssh key filename (default: this hostname)
--github-user NAME sshd: authorize github.com/NAME.keys
--sshd-allow ADDRS sshd: addresses the firewall admits to port 22
--os-upgrade-no-pass Also let this user upgrade the OS packages with no password, and nothing else (below)
--template [PATH] Write the bashrc template to PATH, or stdout
--template-profile [PATH] Write the profile template to PATH, or stdout

Passwordless OS upgrades

--os-upgrade-no-pass is for a machine whose packages are upgraded unattended: over a one-shot ssh, from a timer, or by an agent such as a maintenance bot. None of them has a terminal to type a sudo password into, so sudo -n apt-get upgrade fails with a password is required. The flag grants that one command and no other:

File Owner, mode What it is
/usr/local/sbin/jb-os-upgrade root, 0755 This machine's full upgrade (apt-get update + upgrade, pacman -Syu, dnf upgrade, zypper update or apk upgrade), non-interactive. It takes no arguments and never reboots.
/etc/sudoers.d/jb-os-upgrade root, 0440 <you> ALL=(root) NOPASSWD: /usr/local/sbin/jb-os-upgrade "", where "" means no arguments are allowed.
jbx setup-system -s deps --os-upgrade-no-pass   # asks for your password once
sudo -n jb-os-upgrade                          # from then on, never

A rule naming the package manager itself would also let anyone holding the account run pacman -U <any package>, which amounts to root. The upgrader runs only the commands baked into it when it was written, and it sources nothing a user can edit. visudo checks the rule before it is installed. Afterwards, sudo -n -l confirms it is in effect, so a sudoers file that does not include /etc/sudoers.d is reported rather than trusted.

It is never part of a default run or of bootstrap.toml: a privilege is granted only when asked for by name. On macOS there is nothing to grant, because brew upgrades without sudo. Re-running it is safe, and it asks for no password once the rule is in effect. To undo it, run sudo rm /etc/sudoers.d/jb-os-upgrade /usr/local/sbin/jb-os-upgrade.


Examples

Set up a new machine from scratch

curl -fsSL https://just-buildit.github.io/get-jb.sh | bash
jbx setup-system
exec bash -l

Read the templates without installing anything

jbx setup-system --template          # the interactive half
jbx setup-system --template-profile  # the environment half

Take the shell config and nothing else

jbx setup-system -s shell

Provision a CI runner or container

jbx setup-system -y -x claude,tools

Use it as your project's onboarding command

# bootstrap.toml
[tools.setup-system]
source = "just-bashit:setup-system"
steps  = ["deps", "tools"]

[dev.apt]
packages = ["build-essential", "cmake"]

[dev.pacman]
packages = ["base-devel", "cmake"]
jbx setup-system     # installs the project's packages, then uv + hooks

Dry run

--dry-run prints every command it would run and writes nothing at all — no files, no config, no packages:

jbx setup-system -n -s shell,git
just-bashit setup-system
dry run — nothing will be changed

==> shell — bash configuration
    would run: mkdir -p /home/you/.config/just-bashit ...
    creating:   /home/you/.config/just-bashit/bashrc.sh
    would append to /home/you/.bashrc: if [ -r "$HOME/... "; fi

==> git — global defaults
    git config --global init.defaultBranch main
    ...

summary
    shell:   ok (/home/you/.config/just-bashit)
    git:     ok (9 default(s) set)

The installed report

After the summary, every run (dry runs too) lists what is on the machine: each tool's own --version and the path it runs from. The rows are the deps baseline for this machine's package manager (#180), read from the same table the step installs from, so the two cannot disagree. Each package reports as the command of its own name (cmake), as the commands its table names in provides (build-essential → cc, make), or, when it declares vs_requires, as each Visual Studio id, by the vswhere probe install-deps installs by. After those come gh, uv, pwsh and claude. On native Windows that means cmake, git, clang-cl, pwsh and the C++ workload, not make, cc and pkg-config, which the winget baseline does not install.

A winget install writes the Machine or User PATH in the registry, which only new processes read. So on native Windows the report also searches the registry's PATH directories, after this shell's own. A tool installed by this run is reported where it is, not as missing, and the closing advice names the directory a new window would add.

Claude Code on native Windows

Anthropic's install.sh refuses a Git Bash, MSYS2 or Cygwin shell ("Windows is not supported by this script"), so on native Windows the claude step uses one of the Windows installers Anthropic's setup page lists (#189):

  • winget, Anthropic.ClaudeCode, when winget is there. winget picks the machine's native build itself, win32-arm64 on an ARM64 box even from an emulated x64 Git Bash, the same reason uv comes from winget (#171). It links claude.exe into %LOCALAPPDATA%\Microsoft\WinGet\Links, which goes on this run's PATH and into the closing advice. A WinGet install does not update itself: run winget upgrade Anthropic.ClaudeCode, or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 to have Claude Code run that upgrade for you.
  • install.ps1, through Windows PowerShell, when winget is absent or its install fails. It leaves a self-updating install in ~/.local/bin. It picks its build from $env:PROCESSOR_ARCHITECTURE alone, which reads AMD64 in a PowerShell started from an emulated x64 shell on ARM64. So that one PowerShell is given the machine's architecture first, from the registry check windows-sshd.ps1 makes for the PowerShell MSI (Get-MachineArch).

jbx setup-system -n -s claude prints the command it would run.

The closing advice

When the shell that ran it is now out of date, the run ends by saying why:

open a new shell, or run: exec bash -l
    (.bashrc now sources just-bashit)
    (/c/Program Files/CMake/bin is on the Windows PATH, not this shell's)

Run through the jbx shell function, it applies those changes to your shell instead. Run from PowerShell through get-jb.ps1's functions, which export JB_CALLER=pwsh, none of the bash reasons apply: every jbx call there starts a fresh login bash. You are told to open a new PowerShell window only when an install put a directory on the Windows PATH that this window predates, and you get no advice at all otherwise (#179):

open a new PowerShell window: this one predates these PATH changes
    (/c/Program Files/CMake/bin is on the Windows PATH, not this window's)

Shell compatibility

setup-system.sh needs bash 3.2 or later — the system bash on macOS qualifies. The installed bashrc.sh degrades on the same footing: bash 4 shell options are behind a version check, and readline settings that need a newer readline fail silently rather than erroring.

profile.sh is POSIX sh and is safe to source from dash.