Pulsar OS FastChroot

pulsar-chroot.sh is a single-file helper you keep on your USB stick and run from a terminal in the Pulsar OS Recovery environment. It mounts your installed Pulsar OS (Btrfs) and drops you into a working chroot, with optional SSH-agent support so you can run git over SSH and recover your data.

It is designed for Pulsar OS's disk layout:

Partition / feature	Label	Filesystem	Mounted at (inside chroot)
System root subvolume @	PULSAR_OS	btrfs	/
Home subvolume @home	PULSAR_OS	btrfs	/home
EFI system partition	EFI	vfat	/boot/efi
Recovery partition (optional)	PULSAR_RECOVERY	ext4	/recovery

Detection is automatic (by label, then by scanning Btrfs partitions for the @ subvolume). You can always override it with --device, --efi, etc.

Requirements

The recovery image already ships everything used here:

• bash, util-linux, coreutils, btrfs-progs
• zenity (optional GUI file/folder pickers)
• rsync (fast, resumable folder copies)
• openssh-client (ssh-agent, ssh-add) — usually present in the target OS

Because USB sticks are often formatted as FAT/exFAT (no Unix executable bit), run the script through bash:

sudo bash pulsar-chroot.sh

The script re-executes itself via sudo automatically if it is not root.

Quick start (interactive menu)

sudo bash pulsar-chroot.sh

You get a menu:

1) Mount Pulsar OS (prepare the chroot)
2) Enter chroot with ssh-agent (loads your existing ~/.ssh keys)
3) Enter chroot (plain root shell)
4) Copy SSH keys from the USB into the target + set up agent
5) Copy a folder to the USB / external disk
6) Copy the target user's home to a destination
7) Show status
8) Unmount and clean up
9) Detect devices
0) Quit

Typical recovery session:

1. 1 to mount the system.
2. 2 to enter the chroot; ssh-agent starts inside the chroot and loads the keys that already exist in the original OS (the target user's ~/.ssh), so git clone/pull/push over SSH just works.
3. Only if you need to bring a key from the USB into the target, use 4 first (it copies the files and then offers to enter the chroot).
4. 5 / 6 to copy folders out to the USB.
5. 8 to unmount everything when you are done.

Command line

pulsar-chroot.sh [command] [options]

Commands:

Command	Description
menu	Interactive menu (default)
mount	Mount Pulsar OS and prepare the chroot
umount / unmount	Unmount everything
chroot	Enter the chroot (plain root shell)
ssh	Enter the chroot with ssh-agent + keys loaded
keys	Install SSH keys into the target and prepare the agent
copy SRC [DST]	Copy a folder to a destination (USB)
copy-home	Copy the target user's home to a destination
status	Show mount / device status
detect	Show detected block devices and Btrfs subvolumes
help	Show help

Options:

Option	Description
--device PATH	Root Btrfs partition (e.g. /dev/nvme0n1p3)
--efi PATH	EFI partition to mount
--recovery PATH	PULSAR_RECOVERY partition to mount
--mountpoint DIR	Where to mount the root (default /mnt/pulsar)
--user NAME	Target username (skip the user prompt)
--gui	Also use zenity popups for messages/confirmations
--no-gui	Never use zenity (pure text output/prompts)

Examples:

# Fully non-interactive mount of a specific disk
sudo bash pulsar-chroot.sh --device /dev/nvme0n1p3 mount

# Enter the chroot as a specific user with SSH ready
sudo bash pulsar-chroot.sh --user jaime ssh

# Copy one folder straight to the USB
sudo bash pulsar-chroot.sh copy /mnt/pulsar/home/jaime/Proyectos /run/media/live/USB

How the SSH agent works

When you enter with ssh / option 2, a small helper is written to /tmp/.pulsar-chroot-agent.sh inside the target and sourced before your shell starts. It:

1. Starts ssh-agent with a fixed socket (/tmp/pulsar-ssh-agent.sock).
2. Looks at every private key in the user's ~/.ssh (any key with a PRIVATE KEY header, encrypted or not) and loads it with ssh-add. Encrypted keys prompt for their passphrase on the terminal.
3. Leaves SSH_AUTH_SOCK exported so git/ssh use the agent.
4. Kills the agent when you leave the chroot (unless it was reusing one).

Option 4 (or keys) copies key files you pick (for example from the USB) into the target user's ~/.ssh with the right ownership and permissions, then offers to enter the chroot.

Notes

• Mounts are read-write (recovery often needs to write). The noatime and compress=zstd:1 options match Pulsar OS's own /etc/fstab.
• Host /run is bind-mounted into the chroot, so the USB you booted from (and the folder where this script lives) is also reachable inside the chroot.
• The zenity/text destination chooser shows the physical device name and size (e.g. SanDisk Cruzer Blade 15,5G) next to each mount point, so picking the right USB stick is easy. The same applies to the root/EFI partition pickers.
• /etc/resolv.conf is bind-mounted so DNS works inside the chroot. The real mount path is recorded in /run/pulsar-chroot-resolv.path so a later umount cleans it up even in a separate process.
• If the root partition is not labeled PULSAR_OS, the script scans Btrfs partitions for one containing the @ subvolume.
• Use status to inspect the mount tree and the detected users.

Why I made this?

For people like me whose agent has broken the system and want to back up all data using the pulsar live env. I will add this as options for the recovery env, but for now here it is this script.

Beta