Recovery guide for a SysLinuxOS system installed on a LUKS-encrypted partition that no longer boots because GRUB is corrupted, overwritten, or was never installed correctly. This is the natural follow-up to Restoring GRUB on SysLinuxOS (btrfs with subvolumes): here the btrfs root lives inside a LUKS volume, so it has to be unlocked before the @ subvolume can be mounted.

When you need this

• The PC shows error: no such device or drops into a grub> rescue shell, and the installed system uses LUKS for the root filesystem.
• Another OS (e.g. Windows) was installed after SysLinuxOS and overwrote the boot loader shared on the ESP.
• The ESP (EFI System Partition) is shared between several installs and needs to be rewritten without losing the other NVRAM entries.
• A kernel or GRUB update was interrupted midway on a system with an encrypted root.

Prerequisites

A bootable SysLinuxOS Live USB (MATE or Gnome). The cryptsetup package must be present on the Live (it is, by default). You need the LUKS passphrase of the volume you’re restoring.

1. Unlock the LUKS volume to restore

Identify the encrypted partition with lsblk -f (it shows up as crypto_LUKS), then unlock it:

sudo cryptsetup luksOpen /dev/sdXN sdXN_crypt

sdXN_crypt is an arbitrary mapper name for this recovery session only: it doesn’t need to match what’s in the installed system’s /etc/crypttab. The decrypted volume shows up at /dev/mapper/sdXN_crypt.

2. Mount the btrfs root subvolume (@)

sudo mkdir -p /mnt/sdXN_crypt
sudo mount /dev/mapper/sdXN_crypt /mnt/sdXN_crypt
sudo btrfs subvolume list /mnt/sdXN_crypt   # check the root subvol's name (@)
sudo umount /mnt/sdXN_crypt
sudo mount -o subvol=@ /dev/mapper/sdXN_crypt /mnt/sdXN_crypt

Just like in the non-encrypted case, the chroot only works when you explicitly mount subvol=@, not the top level (subvolid=5).

3. Mount the ESP and the bind mounts

If the ESP is shared with other installs (the typical multi-boot case):

sudo mount /dev/sdYM /mnt/sdXN_crypt/boot/efi
sudo mount --bind /dev  /mnt/sdXN_crypt/dev
sudo mount --bind /proc /mnt/sdXN_crypt/proc
sudo mount --bind /sys  /mnt/sdXN_crypt/sys
sudo mount --bind /run  /mnt/sdXN_crypt/run

Binding /run matters just as much as /dev, /proc and /sys: without it, update-grub inside the chroot won’t see the LUKS device-mapper entries correctly.

4. Reinstall GRUB from the chroot

sudo chroot /mnt/sdXN_crypt /bin/bash -c "
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=SysLinuxOS --recheck
"

--bootloader-id must exactly match the folder that already exists under EFI/ on the ESP (check with ls /boot/efi/EFI/ before installing): get it wrong and a new one gets created, losing the NVRAM entry shared with the other installs.

5. Unlock the other encrypted volumes (for os-prober)

If the same disk or other disks hold further SysLinuxOS installs on LUKS volumes that should appear in the GRUB menu, unlock them before regenerating the configuration:

sudo cryptsetup luksOpen /dev/sdZN other_crypt

A LUKS volume that isn’t unlocked is invisible to os-prober: if an expected entry is missing from the menu, this is the first thing to check.

6. Regenerate the full grub.cfg

sudo chroot /mnt/sdXN_crypt /bin/bash -c "update-grub"

GRUB_ENABLE_CRYPTODISK=y must already be set in the installed system’s /etc/default/grub — if not, add it and re-run both grub-install and update-grub before leaving the chroot.

7. Verify (optional)

sudo grep -n "^menuentry\|^submenu" /mnt/sdXN_crypt/boot/grub/grub.cfg

Confirm the entries for the unlocked encrypted systems are present before rebooting.

8. Unmount everything and close the LUKS volumes

sudo umount /mnt/sdXN_crypt/dev
sudo umount /mnt/sdXN_crypt/proc
sudo umount /mnt/sdXN_crypt/sys
sudo umount /mnt/sdXN_crypt/run
sudo umount /mnt/sdXN_crypt/boot/efi
sudo umount /mnt/sdXN_crypt
sudo cryptsetup luksClose sdXN_crypt
sudo cryptsetup luksClose other_crypt

Keep the order: unmount the bind mounts before the main mount, and only run luksClose once everything is unmounted.

9. Reboot

sudo reboot

Remove the USB drive while it reboots.

Notes for reuse on other machines

• The mapper names (sdXN_crypt, other_crypt) are arbitrary, picked for the session: they don’t need to match /etc/crypttab.
• Unlocking the other encrypted volumes (step 5) is only needed if they should show up in the GRUB menu; non-encrypted btrfs volumes are already detected automatically by os-prober.
• If the multi-boot layout also includes non-encrypted @ subvolumes, the notes in Restoring GRUB on SysLinuxOS (btrfs with subvolumes) about the os-prober bug #921004/#940710 and the automatic fix in syslinuxos-snapshots ≥ 0.3.0 apply here too.

A word of caution

This procedure touches the boot loader and the encrypted volumes of real systems: always double-check with lsblk -f which partition you’re unlocking and which disk grub-install is writing to, especially with several disks attached and several LUKS volumes unlocked at once.

Restoring GRUB on SysLinuxOS with Encrypted Partitions (LUKS)

share

L'articolo Restoring GRUB on SysLinuxOS with Encrypted Partitions (LUKS) proviene da SysLinuxOS.

The terminal-router workspace keeps the router session and the AI observer in two independent panes.

This article follows terminal-router AI assistants on Cisco and Huawei routers. The earlier article introduced the idea of recording a terminal session and allowing Claude Code or Codex to read the log. Version 1.1.0 turns that mechanism into a complete operational workspace for system integrators and network administrators.

The Italian article is available on francoconidi.it. The source code and the technical documentation are published in the fconidi/terminal-router repository.

What changed in the new release

terminal-router opens two independent terminal widgets. The left widget is reserved for the router or switch session. The right widget runs Claude Code or Codex as an observer. The observer reads the recorded output, analyses the device state and answers questions from the operator.

The remote device is never exposed directly to the AI assistant. The operator owns the SSH or serial connection, types the commands and decides whether to apply any suggestion. The assistant does not authenticate to the router and does not need a direct channel to the device.

The new workspace also supports guarded command proposals. This feature is disabled by default. When enabled, every command group is displayed to the operator, validated and sent only after a one time confirmation code is entered.

Workspace architecture

The launcher creates a private tmux server for the workspace and two separate sessions. The router session is recorded under the user directory ~/.claude-logs. The observer session is not recorded by the workspace launcher. The observer follows a stable link to the router log belonging to that workspace.

This isolation prevents a second workspace from redirecting the observer to the wrong device. Pausing and resuming capture also preserve the correct link. The user’s global tmux configuration is not loaded into the private server used by the workspace.

Mouse behavior is deliberately different in the two widgets. In the router widget, selection and copying work as they do in a normal terminal. In the observer widget, the mouse wheel browses up to 50,000 lines of tmux history. Hold Shift while dragging to select text in the observer. Scrolling therefore does not inject arrow key escape sequences into the assistant prompt.

Quick start

After installation, the command without arguments opens the workspace and selects Claude Code when it is available. If Claude Code is not available, Codex is selected.

terminal-router
terminal-router claude
terminal-router codex
terminal-router workspace claude
terminal-router workspace codex

The commands that name an engine require that exact program. If the selected engine is missing or unauthenticated, terminal-router reports the error and does not silently replace it with the other engine.

The first launch displays a security notice. The log contains whatever is printed on screen and the captured output is sent to the AI provider through its authenticated CLI. The user must explicitly acknowledge this condition. Installing the package does not enable recording and does not automatically edit personal configuration files.

Connecting to a router over SSH

Open the SSH connection in the left widget. Host key prompts, password prompts and interaction with the remote shell remain in the router terminal.

ssh admin@192.168.1.1

When the router produces new output, the observer receives it according to the automatic analysis cadence. The operator can ask questions in the right widget, for example requesting an explanation of a routing table, a review of an ACL or an interpretation of the current interface state.

Serial console

The router widget also displays reference commands for a serial console. tio is the recommended program and is installed as a mandatory dependency. screen and picocom are optional alternatives.

tio --list
tio --baudrate 9600 --databits 8 --parity none --stopbits 1 --flow none /dev/ttyUSB0
screen /dev/ttyUSB0 9600
picocom --baud 9600 --databits 8 --parity n --stopbits 1 --flow n /dev/ttyUSB0

Depending on the adapter, the device can be /dev/ttyACM0. When available, the stable path under /dev/serial/by-id/ is preferable. With tio defaults, 115200 8N1 with no flow control, the following is sufficient.

tio /dev/ttyUSB0

Press Ctrl-t q to exit tio. Recording also works with screen and picocom, but guarded command delivery requires tio or ssh to be the foreground program.

Automatic analysis and AI context

The observer groups output after two seconds of quiet time, or after a maximum of five seconds of continuous output. At least ten seconds must pass between automatic requests. Unchanged output does not trigger a new request.

Each request contains up to the latest 128 KiB of router output and the previous exchange. This keeps enough context for typical command results without sending an unbounded session history. The visible assistant scrollback can reach 50,000 lines, which is separate from the bounded snapshot sent to the provider.

A request that has already been submitted may finish after capture is paused. Pausing prevents new automatic analysis. If the AI CLI or its authentication fails, automatic mode stops and can be enabled again after the problem is corrected.

Guarded configuration mode

Configuration mode is disabled at startup and remains active only for the current observer. The AI may propose commands, but the proposal is treated as untrusted input. Every line is validated, the complete group is displayed and nothing is sent until the operator confirms it.

The mode accepts up to 32 commands in one ordered group. Delivery is allowed only when the router widget has an ssh or tio session in the foreground. Shell operators, control characters and embedded newlines are rejected.

:config on
Configure interface Gi0/1 with description UPLINK and enable it

Pending router commands:
1. configure terminal
2. interface Gi0/1
3. description UPLINK
4. no shutdown
5. end

:confirm A1B2C3D4E5F6

The code is valid for 120 seconds and authorizes only the displayed group. New AI analyses wait while the proposal is pending. F9, a transport change or pausing the router pane cancels the pending group. Every line still needs to be reviewed before confirmation, especially when the device is in production.

Global recording and single session recording

terminal-router install enables recording for every interactive terminal opened by the user. It adds marked blocks to ~/.bashrc or ~/.zshrc and to ~/.tmux.conf. Each tmux pane is connected to the logger and ~/.claude-logs/latest points to the newest log.

terminal-router launch creates a self contained session for one task. Hooks are applied only to that tmux session and disappear when it ends. It does not edit ~/.bashrc, ~/.zshrc or ~/.tmux.conf. Terminator and other open terminals remain independent.

Both modes are per user and keep data inside the user home. Do not run the command as root. The configuration belongs to the calling user and sudo would target root’s home directory.

The terminal-router icon is installed in the SysLinuxOS applications menu.

Administrative commands

After install, the shell shortcuts logpause and logresume are available. Detaching from tmux with Ctrl-b d does not stop recording or the observer. Use F9 or terminal-router pause when capture must stop.

Security and privacy

The log contains everything printed on screen. A password typed at an interactive SSH or sudo prompt is normally not recorded because the terminal does not echo it. Secrets that are made visible by the operator are recorded, including passwords in command arguments, tokens in HTTP headers, plaintext exported variables and the output of .env files or private keys.

The ~/.claude-logs directory uses mode 0700 and log files use mode 0600. The logger runs with umask 077. Nightly rotation removes logs older than 30 days. The directory is outside cloud synchronized folders. Pause capture before sensitive work and resume it into a new file afterwards.

The CLI keeps its normal authentication, while the observer disables shell tools and configured integrations and ignores project configuration. Codex runs read only. Use TR_CLAUDE_MODEL or TR_CODEX_MODEL to select a model. The observer language follows the system locale or can be set explicitly with TR_LANGUAGE=en.

Installation on SysLinuxOS

On SysLinuxOS the package is available in the SysLinuxOS Tools repository.

echo "deb https://fconidi.github.io/SysLinuxOS-Tools tirreno main" | sudo tee /etc/apt/sources.list.d/syslinuxos-tools.list
wget -qO- https://fconidi.github.io/SysLinuxOS-Tools/syslinuxos-archive-keyring.asc | sudo tee /usr/share/keyrings/syslinuxos-archive-keyring.asc > /dev/null
sudo apt update
sudo apt install terminal-router
terminal-router

Installation on Debian and Ubuntu

The GitHub repository publishes the Debian package and its SHA 256 checksum.

wget https://github.com/fconidi/terminal-router/releases/download/v1.1.0/terminal-router_1.1.0_all.deb
wget https://github.com/fconidi/terminal-router/releases/download/v1.1.0/terminal-router_1.1.0_all.deb.sha256
sha256sum -c terminal-router_1.1.0_all.deb.sha256
sudo apt install ./terminal-router_1.1.0_all.deb
terminal-router

To build the package from source:

git clone https://github.com/fconidi/terminal-router.git
cd terminal-router
bash build-deb.sh
sudo apt install ./terminal-router_1.1.0_all.deb
terminal-router

The final command must be run as the normal user. The main requirements are Bash, tmux 3.0 or newer, Python 3 with its standard library, tio and Terminator. Cron is recommended for log rotation. The workspace requires an installed and authenticated Claude Code or Codex CLI.

Upgrading from the 1.0 series

Users of global mode should run terminal-router install again after upgrading. The command updates only marked blocks, creates .terminal-router.bak backups and preserves surrounding settings.

An already running tmux server keeps its previously loaded hooks. Reload the configuration with tmux source-file ~/.tmux.conf when needed. In existing panes, use terminal-router pause and terminal-router resume. For a single task, start a fresh terminal-router launch session.

Conclusion

terminal-router 1.1.0 turns terminal recording into a complete AI assisted operating environment for router and switch work. Separating the device pane from the observer pane preserves human control while the log gives the assistant the real context of the session. Guarded configuration adds a controlled path for proposing commands without turning the assistant into an autonomous administrative connection.

For the full documentation, read the terminal-router GitHub repository and the manual installed with the package through man terminal-router.

terminal-router 1.1.0 an integrated AI observer for Cisco and Huawei routers

share

L'articolo terminal-router 1.1.0 an integrated AI observer for Cisco and Huawei routers proviene da SysLinuxOS.

Recovery guide for a SysLinuxOS system that no longer boots because GRUB is corrupted, overwritten (typically after installing Windows in dual-boot), or was never installed correctly. This covers SysLinuxOS’s standard btrfs layout, with the root filesystem in the @ subvolume and @home kept separate.

When you need this

• The PC shows error: no such device or drops straight into a grub> rescue shell.
• No GRUB menu appears at boot; the PC jumps straight to another OS or fails outright.
• Windows was installed after SysLinuxOS and overwrote the boot loader.
• A kernel or GRUB update was interrupted midway.

Prerequisites

You need a bootable SysLinuxOS Live USB (MATE or Gnome build, same procedure either way). Boot the PC from the USB and open a terminal.

1. Identify the disk and subvolumes

Find the btrfs root partition and its subvolumes:

lsblk -f
sudo mount /dev/sdXN /mnt
sudo btrfs subvolume list /mnt

Look for the lines with path @ and path @home. If the disk holds more than one SysLinuxOS install (multiple @ subvolumes), check which one is the system you want to repair before continuing — for instance by inspecting /etc/hostname inside each subvolume. Then unmount the temporary mount:

sudo umount /mnt

2. Mount the right subvolume

Common mistake: mounting the partition at the top level (subvolid=5) instead of the @ subvolume. The chroot only works if you explicitly mount subvol=@:

sudo mount -o subvol=@ /dev/sdXN /mnt
sudo mount /dev/sdXM /mnt/boot/efi   # UEFI systems only, if ESP is a separate partition
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys

If @home lives on a separate subvolume, there’s no need to mount it for a GRUB reinstall — it isn’t touched by this procedure.

3. Enter the chroot

sudo chroot /mnt /bin/bash

From this point, commands run inside the installed system, not the Live environment.

4. Reinstall GRUB

On UEFI systems (the most common case today):

sudo grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=SysLinuxOS --recheck

On legacy BIOS systems, install onto the whole disk (MBR), never a partition:

sudo grub-install --target=i386-pc --recheck /dev/sdX

/dev/sdX is the whole disk (e.g. /dev/sda), never a partition, for legacy BIOS.

5. Regenerate the configuration

sudo update-grub

If the grub-btrfs package is installed, this step also regenerates the SysLinuxOS — snapshots submenu with the latest bootable snapshots. Confirm the command finishes without errors before leaving the chroot: an error here (e.g. a failing /etc/grub.d/ script) leaves the old grub.cfg in place and needs investigating before you reboot.

6. Exit and reboot

exit
sudo umount -R /mnt
sudo reboot

Remove the USB drive while it reboots.

Notes on multi-boot layouts

If the same disk holds several Linux installs on btrfs with @ subvolumes, Debian’s os-prober won’t detect them: it looks for /etc/os-release at the partition’s top level instead of inside /@/etc/os-release (upstream Debian bugs #921004 and #940710, still open). On SysLinuxOS with syslinuxos-snapshots ≥ 0.3.0 this is already handled automatically by a dedicated script that still surfaces them in the GRUB menu.

Notes on encrypted partitions

If another SysLinuxOS install lives on an encrypted partition, mount (unlock) it first so it gets detected, then run:

sudo update-grub

A word of caution

This is a standard GRUB recovery procedure, adapted to SysLinuxOS’s btrfs subvolume layout. Commands like grub-install write to the boot sector: always double-check the target disk (lsblk) before running these commands, especially with more than one disk attached.

Restoring GRUB on SysLinuxOS (btrfs with subvolumes)

share

L'articolo Restoring GRUB on SysLinuxOS (btrfs with subvolumes) proviene da SysLinuxOS.

SysLinuxOS 13.3 ships in both MATE and Gnome editions. Compared to 13.2 it brings a long list of under-the-hood fixes, but the real headline of this release is something else: for the first time, an agentic AI is natively built into the Live session, ready to work on the real running system, disks, filesystems, services, logs with nothing to install or configure. It’s the single biggest leap forward in the project’s history.

The AI Debut in the Live Session

Every SysLinuxOS 13.3 Live image ships ready to use with Claude Code and the Claude desktop app, alongside Codex (CLI) and the ChatGPT desktop app. Boot the Live image, sign in, and you have an AI agent with real access to the running system. Agentic distributions like Omarchy have already brought AI CLIs into everyday desktop use; SysLinuxOS 13.3 brings the same AI into the scenario Live images exist for in the first place: recovery fully aware of the btrfs subvolume layout the system uses by default.

Live distributions have existed for decades for one precise reason: recovery. A system won’t boot, you grab a USB stick, and you try to figure out what’s wrong using the classic toolkit: manual chroot, fdisk, grub-install, reading logs. With SysLinuxOS 13.3 that same scenario changes shape: boot the Live image, open a terminal, launch Claude Code, and describe the problem in plain language. The agent explores the system on its own and proposes or executes, if authorized  the fix.

Real-World Case: Broken GRUB on a Multi-Boot PC

A direct, first-hand test: a multi-boot PC running several Linux distributions on btrfs with subvolumes stops booting because of a corrupted GRUB. The procedure followed:

• Boot from a SysLinuxOS 13.3 Live USB.
• Open a terminal and launch Claude Code.
• Ask, in plain language, to scan the system and reinstall GRUB on the correct btrfs subvolume.
• The agent identifies disks and partitions, recognizes the btrfs layout with its subvolumes (@, @home), locates the one containing the installation to repair, chroots into it, reinstalls GRUB, and regenerates grub.cfg.
• On reboot, the system comes back up — no manual intervention required.

An operation that normally requires specific expertise in GRUB, btrfs, and manual chroot work, carried out end to end by an AI agent acting on its own, starting from a single natural-language request. It’s the clearest possible example of what it means to have AI genuinely built into a recovery Live image.

terminal-system and terminal-router: AI in the Everyday Workflow

Beyond Claude Code and ChatGPT/Codex in their “pure” form, SysLinuxOS 13.3 also ships two tools built for the project itself, already listed as standalone entries in the Live session’s Applications menu:

• terminal-system: a two-panel terminal: on the right you type instructions in plain language (e.g. “create user Pippo”), on the left the AI-generated shell commands are typed and executed in real time. Every command waits for manual confirmation by default; :auto readonly mode runs only genuinely read-only commands without asking.
• terminal-router: built for network administrators: it records tmux sessions of router and switch CLI work (Cisco, Huawei, and similar), so Claude Code can follow what’s happening on the network device in real time during a troubleshooting session.

Their appearance as dedicated entries in the MATE and Gnome Applications menus is part of the broader menu polish carried out in this release.

Security: Allowlist, Not Blocklist

Giving an AI agent access to a real terminal calls for care. terminal-system, now at version 1.1.7, uses an allowlist-based security model: a command runs without confirmation only if its first token is a program explicitly recognized as read-only (ls, cat, grep, git status/log/diff, systemctl status, journalctl, and similar) and contains none of the shell metacharacters that could turn it into something else (redirects, pipes, backticks, $(), ;, &). Everything else always stops for explicit confirmation, even in automatic mode. Each session also runs on its own dedicated, isolated tmux server, and the optional context memory applies best-effort redaction of passwords, tokens, and API keys before storing any output.

Official SysLinuxOS APT Repository

The promise made with 13.2 a dedicated, signed APT repository is now reality. It’s live, GPG-signed, suite tirreno:

curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash

From that point on, keeping SysLinuxOS tools up to date is a plain apt upgrade. Nine packages are available today: distroclone, distroclone-backup, syslinuxos-snapshots, grub-btrfs, syslinuxos-ring-conky, conky-window, librepods, terminal-system, terminal-router.

Under the Hood

• syslinuxos-snapshots 0.3.16:/mnt is now a dedicated btrfs subvolume, excluded from root snapshots: ISO builds, temporarily mounted disks, and other uses of /mnt are no longer captured in system snapshots.
• Snapshot boot on Gnome: fixed a hang that only occurred on Gnome, caused by gdm trying to restart on a read-only-mounted root. Snapshots now boot to console mode, exactly as MATE already did.
• distroClone 1.4.13/1.4.14: fixes to the btrfs-aware build and locale handling, plus an explicit check on the real exit status of xorriso: a failed ISO build is no longer reported as successful.
• terminal-system 1.1.6/1.1.7: fixed a race condition in typing AI-generated commands into the left panel, added a timeout on AI engine calls, and raised daily snapshot retention to 5.

Testing

SysLinuxOS 13.3 has been validated in both MATE and Gnome editions, on systems with native snapper and on clones produced by distroClone, in addition to the real-world GRUB recovery case described above.

SysLinuxOS remains a distribution built for people who work seriously with Linux — but starting with this release, for the first time, facing a broken system no longer means facing it alone.

SysLinuxOS 13.3

share

L'articolo SysLinuxOS 13.3 proviene da SysLinuxOS.

Unlike a generic AI assistant you paste output and errors into by hand, terminal-system lives inside tmux right next to your real shell: the generated command is typed directly into the panel you’re working in, you confirm it (or edit it, or cancel it), and the result stays right there, in your own session.

How it works

A two-panel tmux layout: the left side is a normal shell, where commands actually run; the right side is an instruction prompt. You type what you want to achieve, the AI assistant translates it into one or more shell commands, and those commands are typed into the left panel in real time.

Launch it with the terminal-system command, or from the “Terminal System” entry in the SysLinuxOS Tools menu once installed. By default it starts with Claude Code; if Claude isn’t available it automatically falls back to Codex. To pick the engine explicitly: terminal-system claude or terminal-system codex.

> list files larger than 100MB in this directory
-> ran: find . -maxdepth 1 -type f -size +100M -exec ls -lh {} \;

Session context is opt-in: with :context on, recent instructions and output are passed to the assistant with every request, so it can handle follow-ups (“delete it now”, “retry with sudo”). It’s off by default, so every request starts clean. Either way it’s never written to disk: it disappears the moment you close the session, or right away with :context clear.

Guide: usage options

The right panel accepts both natural-language instructions and special commands starting with :

By default every command, generated or manual, waits for confirmation: Enter to run it, e to edit it first, n to cancel it. That’s the recommended mode for everyday use, you see what’s about to happen before it happens.

:auto readonly only executes a command automatically if its first word is a recognized read-only program (ls, cat, grep, ps, git status/log/diff, systemctl status and similar) and the line contains none of the shell metacharacters that could turn a harmless-looking command into something else (redirects, pipes, backticks, $(), semicolons, &). Anything else always asks, even in this mode. If one AI engine doesn’t respond, terminal-system automatically tries the other one, if available, before giving up.

Safety and awareness

One thing needs to be said plainly: terminal-system runs real commands on your system. It’s not a demo, it’s not a sandbox, if the AI generates a wrong command and you confirm it without looking, that command actually runs.

Some protections are built in:

• In :auto readonly, a command skips confirmation only if it passes two checks: its first word is a recognized read-only program, and the line contains none of the shell metacharacters that could make it do something other than what it looks like (redirects, pipes, backticks, $(), semicolons, &). Anything not explicitly recognized as safe always asks, even in auto-mode.
• As a second safety net, a fixed set of always-dangerous patterns (destructive rm, mkfs, dd onto a device, fork bombs, any recursive chmod on / regardless of mode, shutdown/reboot, killall -9, removing root/sudo/admin users or groups, iptables -F, writes onto devices under /dev) forces manual confirmation regardless of the allowlist.
• When a command is likely interactive (sudo, ssh, passwd, an editor, a pager), focus moves to the left panel: passwords and interactive prompts are typed by you, directly into the shell running the command, never through the assistant.
• terminal-system runs on its own dedicated tmux server, separate from the default one: the mouse shortcuts it sets up for copy-paste don’t touch your other tmux sessions.

But a list of dangerous patterns is not an absolute guarantee, it’s a safety net, not a substitute for judgment. The underlying rule stays the same: read the command before pressing Enter. terminal-system is genuinely good at solving problems on your own system, like disk space vanishing, services that won’t start, wrong permissions, logs to make sense of, precisely because it takes the burden of remembering exact syntax off your shoulders. But what runs on your machine is still your responsibility, not the assistant’s: use :auto readonly only for operations whose effect you understand, and keep it off while exploring a system you don’t know well.

One more limitation, specific to this kind of tool: on compressed instructions that ask for several things at once (“show me everything: kernel, uptime, memory, disk, network, upgradable packages”), the AI model sometimes glues two commands together with no space or semicolon between them (e.g. uname -auptimefree -h...), producing a line that looks like one command but is actually the wrong fusion of two. That’s model behavior, not a bug in the program that generates the command: no prompt wording fully eliminates it, only makes it rarer. On instructions like that, read the [CONFIRM] line more carefully than usual before pressing Enter — if something looks glued together with no space, press e to edit it or n to cancel.

When :context on is active, left-panel output is run through a filter that redacts the most common password/token/API-key patterns before being kept in memory, on a best-effort basis, not a guarantee: check with :context show before relying on it in a session where something sensitive showed up. Instructions and executed commands are still never written to disk either way: they stay in memory for the current tmux session only.

Installation

Debian / Ubuntu — prebuilt package

The GitHub Releases page has a ready-made .deb, no cloning required:

wget https://github.com/fconidi/terminal-system/releases/latest/download/terminal-system_1.1.7_all.deb
sudo apt install ./terminal-system_1.1.7_all.deb

Or build it from source instead:

git clone https://github.com/fconidi/terminal-system.git
cd terminal-system
bash build-deb.sh
sudo apt install ./terminal-system_*_all.deb

SysLinuxOS

Already packaged in the official APT repository:

curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash
sudo apt update && sudo apt install terminal-system

Requires bash, tmux, xclip (for mouse-drag copy), and the claude and/or codex CLI already installed and authenticated, neither is a hard package dependency, since neither ships as a .deb on this system.

Version history

• 1.0.0  initial release: two-panel tmux launcher, ts-brain instruction REPL, manual confirmation with edit/cancel, danger-pattern guardrail, focus handoff for interactive commands
• 1.1.0  icon and SysLinuxOS Tools menu entry, mouse scrolling in both panels, up/down arrow history recall in the instruction prompt
• 1.1.1  mouse-drag selection now copies to the system clipboard via xclip (was missing on VTE terminals like mate-terminal), fixed codex use outside a git/trusted directory
• 1.1.3  types commands in 6-character chunks instead of one at a time (~6x fewer subprocesses), AI model configurable via TS_CLAUDE_MODEL/TS_CODEX_MODEL
• 1.1.5  replaced :auto on‘s denylist with a read-only command allowlist (:auto readonly); session memory is now opt-in (:context on|off|show|clear) with automatic secret redaction; runs on its own dedicated tmux server instead of the one shared with other sessions
• 1.1.6  the queue of generated commands now stops if a panel stays busy past 120s (e.g. an unanswered sudo password prompt), instead of continuing to type over a still-pending command
• 1.1.7  each command is now typed in a single call instead of in chunks (in rare cases, on long commands, chunked typing could desync tmux from the typed text); tightened the AI system prompt to reduce (not eliminate) glued-together commands — see the note in “Security and awareness”

Useful links

• Source code and prebuilt .deb on GitHub (also useful outside SysLinuxOS): github.com/fconidi/terminal-system
• APT repository: fconidi.github.io/SysLinuxOS-Tools
• Run man terminal-system after installing for the full documentation

terminal-system: AI-assisted terminal (Claude Code, Codex) for your Linux system

share

L'articolo Terminal-system AI assistant (Claude Code, Codex) for your Linux system proviene da SysLinuxOS.

terminal-router is the SysLinuxOS package built for exactly that: it records your terminal session to a file an AI assistant can follow live, while you stay the only one actually typing commands on the device.

How it works

The workflow is simple: you open an SSH session to the router in one pane, the assistant tails ~/.claude-logs/latest in another. You type, it reads and suggests, you decide what to run. The log never leaves the machine.

Under the hood it relies on tmux: each pane is piped to a logger script that writes a timestamped file, with an always-current latest symlink pointing at the newest pane.

Two ways to enable it

Since 1.0.4, terminal-router offers two distinct modes:

terminal-router install — every terminal

Adds a marked block to ~/.bashrc (or ~/.zshrc) and to ~/.tmux.conf: from then on, every interactive terminal you open automatically enters a logged tmux session. Convenient if you work on network devices often and want logging always on, but it does touch your shell configuration — it stays active across reboots until you explicitly run terminal-router remove.

terminal-router launch — one session, zero config changes

The new option for when you want to log just that one session, without touching Terminator, GNOME Terminal, or any other terminal you already have open. terminal-router launch starts a self-contained tmux session with pipe-pane hooks scoped to that session only (no -g flag): when it ends, the hooks vanish with it, and nothing is ever written to ~/.bashrc, ~/.zshrc, or ~/.tmux.conf.

One implementation detail worth sharing: chaining pipe-pane right after new-session in a single tmux invocation turns out to be unreliable — verified empirically on tmux 3.5a, the pipe silently never attaches to that first pane. The fix sets the hooks on the session first, then swaps the initial (never logged) window for a new one created after the hooks exist, which does get captured correctly.

Installation

terminal-router ships through the official SysLinuxOS Tools APT repository. If you haven’t added it yet:

curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash

Then install the package like any other:

sudo apt update
sudo apt install terminal-router

Installing the package enables nothing by itself — each user has to explicitly choose install or launch and accept the security notice once.

Commands

Inside a logged pane, two shell functions help around sensitive moments:

logpause    # suspends logging for this pane
logresume   # resumes it, into a new file

New in 1.0.5: AI assistant check

Logging a session only matters if something actually reads it. As of this version, install, launch, and status check whether claude or codex is available on PATH, and warn — without blocking anything — if neither is found:

$ terminal-router status
...
  AI assistant    found      (claude codex)

Note for Codex-via-nvm setups: it’s only detected if the shell running the check has already loaded nvm into its environment.

Security: what ends up in the log (and what doesn’t)

The log captures everything printed on screen. It does not capture passwords typed at an interactive prompt (sudo, SSH password authentication) — the terminal never echoes them, so tmux never sees them either.

What can end up in the log, because it’s visible on screen:

• passwords passed as plaintext arguments (e.g. mysql -pXXX)
• tokens in HTTP headers (e.g. curl -H "Authorization: Bearer ...")
• the output of cat on a .env file or a private key

Mitigations already in place: log directory at 0700, files at 0600, automatic rotation after 30 days, plus the logpause/logresume pair for the moments you need to work quietly.

Version history

• 1.0.3 — fixed a bug that left APT locked while using the CLI wrapper
• 1.0.4 — new launch command: a non-invasive single session, no bashrc/tmux.conf edits
• 1.0.5 — automatic detection of claude/codex, with a warning when no AI assistant is around to read the log

Useful links

• APT repository: fconidi.github.io/SysLinuxOS-Tools
• Source code on GitHub (also useful outside SysLinuxOS, to build the .deb on any Debian/Ubuntu): github.com/fconidi/terminal-router
• Run man terminal-router after installing for the full documentation

Terminal-router AI assistants (Claude Code, Codex) on Cisco/Huawei routers

share

L'articolo Terminal-router AI assistants (Claude Code, Codex) on Cisco/Huawei routers proviene da SysLinuxOS.

/mnt/SysLinuxOS_backup/

├── .backup_meta          ← metadata file (date, distro, size)
└── .rootfs_cache/        ← btrfs subvolume (the live rsync target)
    └── .snapshots/       ← btrfs subvolume managed by snapper
        ├── 1/
        │   ├── info.xml
        │   └── snapshot/ ← read-only btrfs snapshot of .rootfs_cache
        ├── 2/
        │   ├── info.xml
        │   └── snapshot/
        └── ...

META_DATE="2026-06-17 14:30"
META_DISTRO="SysLinuxOS"
META_SIZE="8.2G"

2026-06-17 14:30 | SysLinuxOS | 8.2G

[ ] Build from DCB cache (2026-06-17 14:30 | SysLinuxOS | 8.2G)

if [ "$SOURCE_MODE" != "cache" ] && [ "$SOURCE" != "/" ]; then
    # live validation only runs in live mode
fi

--exclude=/.snapshots
--exclude=/.snapshots/*
--exclude=/@.rollback-bak-*

btrfs root (top-level, subvolid=5)
├── @               ← mounted at /
├── @home           ← mounted at /home
└── .snapshots      ← snapper snapshots of @ /mnt/SysLinuxOS_backup/ (separate btrfs volume or subvolume)
└── .rootfs_cache/  ← subvolume, rsync target
    └── .snapshots/ ← subvolume, snapper config "distroclone-backup"
        ├── 1/snapshot   (read-only)
        ├── 2/snapshot   (read-only)
        └── ...

# 1. Delete each read-only snapshot leaf
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots/1/snapshot
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots/2/snapshot
# ... repeat for each numbered snapshot

# 2. Delete the .snapshots subvolume itself
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots

# 3. Delete the .rootfs_cache subvolume
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache

# 4. Now rm -rf works on the remainder
sudo rm -rf /mnt/SysLinuxOS_backup/

curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash
sudo apt install distroclone distroclone-backup snapper btrfs-progs

wget https://github.com/fconidi/distroClone/releases/latest/download/distroClone_1.4.10_all.deb
wget https://github.com/fconidi/distroClone-backup/releases/latest/download/distroclone-backup_1.3.4_all.deb
sudo apt install ./distroClone_1.4.10_all.deb ./distroclone-backup_1.3.4_all.deb

share

L'articolo Build a Live ISO from DistroClone Backup Cache proviene da SysLinuxOS.

I am excited to announce that the official SysLinuxOS AP  is now live and publicly accessible. All SysLinuxOS tools and packages are now installable and upgradable directly via apt, with GPG signature verification and automatic updates.

What it is

The SysLinuxOS-Tools repository is a GPG-signed APT repository hosted on GitHub Pages and managed with reprepro. It distributes the packages developed for SysLinuxOS: tools that extend Debian with snapshot management, live ISO creation, system monitoring and more.

Repository URL: https://fconidi.github.io/SysLinuxOS-Tools

Source code and metadata on GitHub: https://github.com/fconidi/SysLinuxOS-Tools

Available packages (repo constantly updated)

• distroclone — builds a bootable live ISO directly from your running Debian system
• distroclone-backup — automatic Btrfs snapshot integration for distroClone
• grub-btrfs — Btrfs snapshots in the GRUB menu (SysLinuxOS build)
• syslinuxos-ring-conky — ring-style Conky theme with auto-scaling
• syslinuxos-snapshots — Btrfs snapshot management with GRUB integration
• conky-window — minimal Conky window theme for SysLinuxOS

Tip

After installing SysLinuxOS 13.2, I recommend reinstalling the packages, to update configuration files, and align all packages with apt.

Installation

A single command sets up the repository, imports the GPG key and configures the APT source:

curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash

After that, install any package as usual:

sudo apt install syslinuxos-snapshots
sudo apt install syslinuxos-ring-conky
sudo apt install distroclone

Updates will be delivered automatically via apt upgrade, like any standard Debian package.

Manual setup

If you prefer to configure the repository by hand:

# Import the signing key
curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/syslinuxos-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/syslinuxos-archive-keyring.gpg

# Add the APT source (deb822 format)
sudo tee /etc/apt/sources.list.d/syslinuxos-tools.sources >/dev/null <<'EOF'
Types: deb
URIs: https://fconidi.github.io/SysLinuxOS-Tools
Suites: tirreno
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/syslinuxos-archive-keyring.gpg
EOF

sudo apt update

Technical details

• Hosting: GitHub Pages (branch main)
• Signing: GPG RSA-4096, key ID 5FADCAF45BC3FA1D
• Suite: tirreno — Component: main — Architecture: amd64
• Package management: reprepro — one version per package, index rebuilt and re-signed on each update

The grub-btrfs package is a customized build for SysLinuxOS. To ensure it always takes precedence over any Debian-provided version, the install script configures an APT pin at priority 1001 in /etc/apt/preferences.d/99-syslinuxos-tools.pref. No other packages are pinned.

Why a dedicated repository

Managing SysLinuxOS packages individually — downloading .deb files, tracking versions, running dpkg -i manually — is error-prone and does not scale. A proper APT repository means:

• Packages are installed and upgraded with standard apt commands
• GPG signature verification on every apt update
• Correct dependency resolution handled by APT
• No manual intervention needed when new versions are released

The repository is already used in the SysLinuxOS ISO build process and on all active SysLinuxOS installations.

Franco Conidi aka edmond — francoconidi.it — syslinuxos.com

share

L'articolo SysLinuxOS Official APT Repository Now Live proviene da SysLinuxOS.

SysLinuxOS – Snapshot Management Guide

1. Introduction

SysLinuxOS 13.2 uses btrfs as its default filesystem and integrates snapper, grub-btrfs, and the syslinuxos-rollback helper to provide automatic, GRUB-bootable filesystem snapshots.

Every time the system is updated or a snapshot is created manually, a copy of the root filesystem is stored in /.snapshots. These snapshots appear as boot entries in the GRUB menu, making it possible to boot into a previous state without losing data or needing a live ISO.

This guide covers the commands you will use day-to-day to inspect, create, delete, and restore snapshots on SysLinuxOS.

2. Requirements

The following packages must be installed and active (default in SysLinuxOS):

• syslinuxos-snapshots — provides syslinuxos-rollback, the grub.d helpers, and the setup script
• snapper >= 0.10
• grub-btrfs >= 4.14
• btrfs-progs

To verify the setup is complete:

sudo snapper -c root list
systemctl status snapper-timeline.timer snapper-cleanup.timer grub-btrfsd.service

If /.snapshots is missing or the snapper config does not exist, re-run the setup:

sudo /usr/sbin/syslinuxos-snapshots-setup

3. Viewing Snapshots

List all existing snapshots:

sudo snapper -c root list

The output shows the snapshot number, type (single, pre, post), date, description, and whether the snapshot is read-only. Row 0 is always the current live state and is not a real snapshot.

To show detailed information about a specific snapshot:

sudo snapper -c root info N

Replace N with the snapshot number.

4. Creating a Snapshot

Create a manual single snapshot with a description:

sudo snapper -c root create --description "before kernel upgrade" --type single

Create a pre/post pair around an operation (for example a package install):

sudo snapper -c root create --type pre --description "pre apt upgrade"
sudo apt upgrade
sudo snapper -c root create --type post --description "post apt upgrade"

5. Deleting Snapshots

Delete a single snapshot by number:

sudo snapper -c root delete N

Delete a range of snapshots:

sudo snapper -c root delete N-M

Snapper also runs automatic cleanup via the snapper-cleanup.timer service. The active limits are:

• Maximum regular snapshots kept: 5
• Maximum important snapshots kept: 5
• Daily timeline snapshots kept: 7
• GRUB snapshot entries shown: 8

These values are set by syslinuxos-snapshots-setup and can be overridden manually:

sudo snapper -c root set-config "NUMBER_LIMIT=10"
sudo snapper -c root set-config "TIMELINE_LIMIT_DAILY=14"

6. Automatic Snapshots (Timeline)

The timeline creates one snapshot per hour and keeps the most recent daily snapshots according to the configured limits. This is handled by two systemd timers:

systemctl status snapper-timeline.timer
systemctl status snapper-cleanup.timer

To check the timeline configuration:

sudo snapper -c root get-config

Timeline creation is enabled by default (TIMELINE_CREATE="yes"). To disable it:

sudo snapper -c root set-config "TIMELINE_CREATE=no"

7. Booting from a Snapshot (GRUB)

At boot, the GRUB menu includes a submenu named SysLinuxOS — snapshots. Select a snapshot entry to boot the system in the state it was at the time the snapshot was taken.

The system boots from a read-only copy of the snapshot. From this temporary state you can verify the system works and then decide whether to proceed with the rollback.

The submenu is generated by grub-btrfsd, which monitors /.snapshots and updates /boot/grub/grub-btrfs.cfg automatically when snapshots are created or deleted. To regenerate it manually:

sudo update-grub

8. Rolling Back to a Snapshot

Rolling back replaces the current root subvolume (@) with a read-write copy of the chosen snapshot. The previous @ is preserved as @.rollback-bak-<timestamp> on the btrfs top-level volume for recovery purposes.

8.1 Method 1 — From a Booted Snapshot (Recommended)

Boot into the snapshot you want to restore via the GRUB snapshot submenu, then run:

sudo syslinuxos-rollback

The tool auto-detects the snapshot number from the current subvolume path.

8.2 Method 2 — From the Running System or a Live ISO

Pass the snapshot number explicitly:

sudo syslinuxos-rollback N

In both cases the tool asks for confirmation before making any changes, then prints the steps it will execute:

1. Rename @ to @.rollback-bak-<timestamp>
2. Create a new read-write @ from snapshot N
3. Recreate @/.snapshots as an empty btrfs subvolume (snapper resumes normally)

After the tool completes, reboot:

sudo reboot

After verifying the rolled-back system works correctly, you can delete the backup subvolume (see the next section).

9. Cleaning Up Rollback Backups

Each rollback leaves a @.rollback-bak-<timestamp> subvolume on the btrfs top-level volume. These are kept intentionally as a safety net and do not appear in the GRUB snapshot menu.

To list and remove them:

sudo mkdir -p /mnt/tmp
sudo mount -o subvolid=5 /dev/sdXN /mnt/tmp
ls /mnt/tmp | grep rollback-bak
sudo btrfs subvolume delete -R -c /mnt/tmp/@.rollback-bak-<timestamp>
sudo umount /mnt/tmp

Replace /dev/sdXN with your btrfs partition (visible with lsblk).

10. Accessing Snapshots from Another SysLinuxOS Install

If multiple SysLinuxOS installs are present on different partitions, the GRUB menu includes two additional sections generated by the syslinuxos-snapshots package:

• Other Linux installs on btrfs: top-level entry for each secondary install plus an Advanced options submenu with all available kernels and recovery entries. This replaces the missing os-prober detection for btrfs @ layouts (Debian bugs 921004, 940710).
• SysLinuxOS — Snapshots of other installs: a submenu that chainloads the grub-btrfs.cfg of each secondary install. Selecting an entry boots that install’s specific snapshot.

Both sections are generated by /etc/grub.d/13_syslinuxos-btrfs-otheros and /etc/grub.d/14_syslinuxos-snapshots-otheros. They can be disabled individually in /etc/default/grub:

GRUB_DISABLE_BTRFS_OTHEROS=true
GRUB_DISABLE_BTRFS_SNAPSHOTS_OTHEROS=true

After changing these variables, regenerate the GRUB configuration:

sudo update-grub

10.1 LUKS-encrypted installs

Starting with syslinuxos-snapshots 0.3.15, /etc/grub.d/13_syslinuxos-btrfs-otheros automatically handles secondary installs protected by LUKS full-disk encryption. When the LUKS container is already open at the time update-grub runs, the script detects the encrypted device and generates a boot entry that includes the required cryptomount directive — no manual editing of /etc/grub.d/40_custom required.

Open the LUKS container before running update-grub (the mapper name does not matter):

sudo cryptsetup luksOpen /dev/nvme0n1pX any_name
sudo update-grub
sudo cryptsetup close any_name

At boot, GRUB asks for the LUKS passphrase once to load the kernel and initrd from the encrypted partition. The initramfs then prompts a second time to mount the encrypted root filesystem.

11. Re-running Setup

The setup script is idempotent and safe to re-run at any time. It will skip steps that are already complete and only apply what is missing:

sudo /usr/sbin/syslinuxos-snapshots-setup

Use this after a manual change to the snapper configuration, after a failed snapper-boot.service, or when setting up a system that was installed without the syslinuxos-snapshots package.

share

L'articolo SysLinuxOS Snapshot Management Guide proviene da SysLinuxOS.

sudo syslinuxos-install-extras networking   # DNS, DHCP, VPN, BGP/OSPF, HA, proxy, SNMP, IDS
sudo syslinuxos-install-extras devops       # monitoring, logging, containers, K8s, IaC
sudo syslinuxos-install-extras cloud        # AWS/Azure/GCP CLI, virtualization, storage, K8s
sudo syslinuxos-install-extras full         # all TIER2 in one operation
sudo syslinuxos-install-extras repos        # add official Grafana, HashiCorp, Helm APT repos

share

L'articolo SysLinuxOS 13.2 Revolution proviene da SysLinuxOS.