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:
-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:
It asks Windows for its trusted roots through powershell.exe:
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:
- creates
%USERPROFILE%\<Folder>; - 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; - sets the value, and any other value in the key that names the same folder
(Documents has a second one,
{F42EE2D3-…}), to%USERPROFILE%\<Folder>asREG_EXPAND_SZ; - 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;
- when Documents moved and
get-jb.ps1installed 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:
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:
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:
- from
GIT_AUTHOR_NAME/GIT_AUTHOR_EMAILwhen those are exported; - otherwise asked for, when stdin is a terminal and
--yeswas not given (an empty answer skips it); - 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.
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-channelinwindows.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 reportedskipped (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:
- Adds
github.com/<user>.keysto~/.ssh/authorized_keys, keeping any key already there. Nothing re-reads them later; re-running the step is the refresh. - 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. - Turns password and keyboard-interactive login off, with
/etc/ssh/sshd_config.d/050-just-bashit.conf— named to sort before macOS's own100-macos.conf, sincesshdkeeps the first value it reads. Only whenauthorized_keyshas a key, so it cannot lock you out; the file is checked withsshd -tand removed again ifsshdrejects it. Deleting it turns passwords back on.
--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¶
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¶
Provision a CI runner or container¶
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"]
Dry run¶
--dry-run prints every command it would run and writes nothing at all —
no files, no config, no packages:
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-arm64on an ARM64 box even from an emulated x64 Git Bash, the same reasonuvcomes from winget (#171). It linksclaude.exeinto%LOCALAPPDATA%\Microsoft\WinGet\Links, which goes on this run'sPATHand into the closing advice. A WinGet install does not update itself: runwinget upgrade Anthropic.ClaudeCode, or setCLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1to 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_ARCHITECTUREalone, which readsAMD64in a PowerShell started from an emulated x64 shell on ARM64. So that one PowerShell is given the machine's architecture first, from the registry checkwindows-sshd.ps1makes 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.