From 237956b39aaf8d1ef7f355ee33d13b11978d538e Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 11:58:39 +0100 Subject: [PATCH 01/19] feat: add gentle-shell (LXC dev server for the gentle-shell coding-agent workspace) --- ct/gentle-shell.sh | 101 ++++++++++++++++++++++++++++++++ install/gentle-shell-install.sh | 40 +++++++++++++ json/gentle-shell.json | 86 +++++++++++++++++++++++++++ 3 files changed, 227 insertions(+) create mode 100644 ct/gentle-shell.sh create mode 100644 install/gentle-shell-install.sh create mode 100644 json/gentle-shell.json diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh new file mode 100644 index 0000000000..8d4659d531 --- /dev/null +++ b/ct/gentle-shell.sh @@ -0,0 +1,101 @@ +#!/usr/bin/env bash +_CS_DEFAULT_URL="https://raw.githubusercontent.com/community-scripts/DevScripts/main" +_cs_boot="${COMMUNITY_SCRIPTS_CORE_DIR:-$(dirname "${BASH_SOURCE[0]}")/../../core}/core/build.func" +source "$_cs_boot" 2>/dev/null || source <(curl -fsSL "${COMMUNITY_SCRIPTS_CORE_URL:-https://raw.githubusercontent.com/community-scripts/core/main}/core/build.func") +# Copyright (c) 2021-2026 community-scripts ORG +# Author: Gentleman-Programming +# License: MIT | https://github.com/community-scripts/DevScripts/raw/main/LICENSE +# Source: https://github.com/Gentleman-Programming/gentle-shell + +APP="gentle-shell" +var_tags="${var_tags:-development;ai;coding-agent}" +var_cpu="${var_cpu:-2}" +var_ram="${var_ram:-2048}" +var_disk="${var_disk:-10}" +var_os="${var_os:-debian}" +var_version="${var_version:-13}" +var_arm64="${var_arm64:-yes}" +var_unprivileged="${var_unprivileged:-1}" +var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issues/NEW}" + +var_hostname="${var_hostname:-}" +var_projects_mode="${var_projects_mode:-internal}" +var_projects_storage="${var_projects_storage:-}" +var_projects_size="${var_projects_size:-10}" +var_gh_token="${var_gh_token:-}" + +header_info "$APP" +variables +color +catch_errors + +if [[ -z "${var_hostname}" ]]; then + read -rp " Machine name for Herdr (default: gentle-shell): " -t 60 var_hostname || var_hostname="" +fi +var_hostname="${var_hostname:-gentle-shell}" + +if [[ -z "${var_projects_mode}" ]]; then + read -rp " Store projects [1] inside the LXC disk or [2] on an external Proxmox mountpoint (default: 1): " -t 60 var_projects_mode || var_projects_mode="1" +fi +case "${var_projects_mode}" in + 2 | external) var_projects_mode="external" ;; + *) var_projects_mode="internal" ;; +esac + +if [[ "${var_projects_mode}" == "external" ]]; then + if [[ -z "${var_projects_storage}" ]]; then + read -rp " Proxmox storage for the projects mountpoint (default: local-lvm): " -t 60 var_projects_storage || var_projects_storage="" + fi + var_projects_storage="${var_projects_storage:-local-lvm}" + if ! pvesm status 2>/dev/null | awk 'NR>1 {print $1}' | grep -qx "${var_projects_storage}"; then + msg_error "Storage '${var_projects_storage}' does not exist on this Proxmox host!" + exit 1 + fi + if [[ -z "${var_projects_size}" ]]; then + read -rp " Projects volume size in GB (default: 10): " -t 60 var_projects_size || var_projects_size="" + fi + var_projects_size="${var_projects_size:-10}" +fi + +export var_hostname var_projects_mode var_projects_storage var_projects_size var_gh_token + +function update_script() { + header_info + check_container_storage + check_container_resources + + if ! command -v gentle-shell &>/dev/null; then + msg_error "No ${APP} Installation Found!" + exit + fi + + RELEASE=$(npm view gentle-pi version 2>/dev/null) + if [[ -z "${RELEASE}" ]]; then + msg_error "Unable to reach npm for the latest gentle-pi version." + exit + fi + msg_info "Updating ${APP} (gentle-pi@${RELEASE})" + $STD npm install -g "gentle-pi@${RELEASE}" + msg_ok "Updated ${APP}" + exit +} + +start +build_container + +if [[ "${var_projects_mode}" == "external" ]]; then + msg_info "Attaching Projects Volume (${var_projects_storage}:${var_projects_size}GB)" + pct set "${CTID}" -mp0 "${var_projects_storage}:${var_projects_size},mp=/mnt/projects" + if ! pct exec "${CTID}" -- test -d /mnt/projects 2>/dev/null; then + pct reboot "${CTID}" + pct wait "${CTID}" running + fi + pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects + msg_ok "Attached Projects Volume" +fi + +description + +msg_ok "Completed Successfully!\n" +echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}" +echo -e "${INFO}${YW}Connect via SSH (root) and run 'gentle-shell'; projects live in /root/projects.${CL}" diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh new file mode 100644 index 0000000000..d02ea9e9f4 --- /dev/null +++ b/install/gentle-shell-install.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash + +# Copyright (c) 2021-2026 community-scripts ORG +# Author: Gentleman-Programming +# License: MIT | https://github.com/community-scripts/DevScripts/raw/main/LICENSE +# Source: https://github.com/Gentleman-Programming/gentle-shell + +source /dev/stdin <<<"$FUNCTIONS_FILE_PATH" +color +verb_ip6 +catch_errors +setting_up_container +network_check +update_os + +msg_info "Installing Dependencies" +$STD apt install -y git +msg_ok "Installed Dependencies" + +NODE_VERSION="22" setup_nodejs + +fetch_and_deploy_gh_release "gh" "cli/cli" "binary" + +msg_info "Installing gentle-shell (gentle-pi)" +$STD npm install -g gentle-pi +msg_ok "Installed gentle-shell" + +if [[ -n "${var_gh_token:-}" ]]; then + msg_info "Authenticating GitHub CLI" + printf '%s' "${var_gh_token}" | gh auth login --with-token + msg_ok "Authenticated GitHub CLI" +fi + +if [[ "${var_projects_mode:-internal}" != "external" ]]; then + mkdir -p /root/projects +fi + +motd_ssh +customize +cleanup_lxc diff --git a/json/gentle-shell.json b/json/gentle-shell.json new file mode 100644 index 0000000000..4eba34b6bf --- /dev/null +++ b/json/gentle-shell.json @@ -0,0 +1,86 @@ +{ + "name": "gentle-shell", + "slug": "gentle-shell", + "categories": [ + 20 + ], + "date_created": "2026-11-18", + "type": "ct", + "platforms": ["pve"], + "architectures": ["amd64", "arm64"], + "updateable": true, + "privileged": false, + "interface_port": null, + "documentation": "https://github.com/Gentleman-Programming/gentle-shell", + "website": "https://gentlemanprogramming.com/", + "repository": "https://github.com/Gentleman-Programming/gentle-shell", + "logo": "https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/gentle-shell.webp", + "description": "gentle-shell is a coding-agent workspace and TUI harness built for Pi: agent orchestration, ODD workflow tracking, native review, diff views and persistent memory, driven from the terminal. This script creates an LXC development server with gentle-shell, git and the GitHub CLI preinstalled, ready to be used over SSH.", + "install_methods": [ + { + "type": "default", + "script": "ct/gentle-shell.sh", + "resources": { + "cpu": 2, + "ram": 2048, + "hdd": 10, + "os": "Debian", + "version": "13" + } + } + ], + "default_credentials": { + "username": null, + "password": null + }, + "notes": [ + { + "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its setup completes on first launch. Projects live in /root/projects.", + "type": "info" + }, + { + "text": "To use it as a Herdr dev server, add this container to ~/.ssh/config on your desktop machine (Host , User root) and select it with Add Machine in Herdr.", + "type": "info" + }, + { + "text": "Without a GitHub token, run 'gh auth login' inside the container to authenticate the GitHub CLI.", + "type": "info" + } + ], + "app_vars": [ + { + "name": "var_hostname", + "label": "Machine Name", + "type": "text", + "default": "gentle-shell", + "help": "Container hostname; Herdr shows it as the remote machine name" + }, + { + "name": "var_projects_mode", + "label": "Projects Storage", + "type": "text", + "default": "internal", + "help": "internal = /root/projects on the LXC disk; external = a new mountpoint on a Proxmox storage" + }, + { + "name": "var_projects_storage", + "label": "Proxmox Storage (external mode)", + "type": "text", + "help": "Proxmox storage for the projects volume, e.g. local-lvm (external mode only)" + }, + { + "name": "var_projects_size", + "label": "Projects Volume Size (GB)", + "type": "number", + "default": 10, + "help": "Size in GB of the external projects volume (external mode only)" + }, + { + "name": "var_gh_token", + "label": "GitHub Token", + "type": "password", + "secret": true, + "help": "Optional GitHub PAT; when empty, authenticate later with 'gh auth login' inside the container" + } + ] +} From ac91403d1ae8d1910e601f7c5eec560aed600eff Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 12:14:30 +0100 Subject: [PATCH 02/19] fix: make projects prompts reachable, validate mount storage content and mount activation --- ct/gentle-shell.sh | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 8d4659d531..d547799849 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -19,9 +19,9 @@ var_unprivileged="${var_unprivileged:-1}" var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issues/NEW}" var_hostname="${var_hostname:-}" -var_projects_mode="${var_projects_mode:-internal}" +var_projects_mode="${var_projects_mode:-}" var_projects_storage="${var_projects_storage:-}" -var_projects_size="${var_projects_size:-10}" +var_projects_size="${var_projects_size:-}" var_gh_token="${var_gh_token:-}" header_info "$APP" @@ -47,8 +47,8 @@ if [[ "${var_projects_mode}" == "external" ]]; then read -rp " Proxmox storage for the projects mountpoint (default: local-lvm): " -t 60 var_projects_storage || var_projects_storage="" fi var_projects_storage="${var_projects_storage:-local-lvm}" - if ! pvesm status 2>/dev/null | awk 'NR>1 {print $1}' | grep -qx "${var_projects_storage}"; then - msg_error "Storage '${var_projects_storage}' does not exist on this Proxmox host!" + if ! pvesm status -content rootdir 2>/dev/null | awk 'NR>1 {print $1}' | grep -qx "${var_projects_storage}"; then + msg_error "Storage '${var_projects_storage}' does not exist or cannot hold container mountpoints!" exit 1 fi if [[ -z "${var_projects_size}" ]]; then @@ -66,13 +66,13 @@ function update_script() { if ! command -v gentle-shell &>/dev/null; then msg_error "No ${APP} Installation Found!" - exit + exit 1 fi RELEASE=$(npm view gentle-pi version 2>/dev/null) if [[ -z "${RELEASE}" ]]; then msg_error "Unable to reach npm for the latest gentle-pi version." - exit + exit 1 fi msg_info "Updating ${APP} (gentle-pi@${RELEASE})" $STD npm install -g "gentle-pi@${RELEASE}" @@ -86,10 +86,14 @@ build_container if [[ "${var_projects_mode}" == "external" ]]; then msg_info "Attaching Projects Volume (${var_projects_storage}:${var_projects_size}GB)" pct set "${CTID}" -mp0 "${var_projects_storage}:${var_projects_size},mp=/mnt/projects" - if ! pct exec "${CTID}" -- test -d /mnt/projects 2>/dev/null; then + if ! pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then pct reboot "${CTID}" pct wait "${CTID}" running fi + if ! pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then + msg_error "Projects mountpoint on '${var_projects_storage}' did not activate; check the container config." + exit 1 + fi pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects msg_ok "Attached Projects Volume" fi From ed7fcabf9e1ae961b7e7708c0b2da5b93902ba2c Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 13:29:11 +0100 Subject: [PATCH 03/19] feat: prompt for an optional GitHub PAT with creation and device-flow guidance --- ct/gentle-shell.sh | 8 ++++++++ json/gentle-shell.json | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index d547799849..a32c987b80 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -57,6 +57,14 @@ if [[ "${var_projects_mode}" == "external" ]]; then var_projects_size="${var_projects_size:-10}" fi +if [[ -z "${var_gh_token}" ]]; then + echo -e "${INFO}${YW}GitHub account (optional): to authenticate now, create a Personal Access Token at${CL}" + echo -e "${YW}github.com -> Settings -> Developer settings -> Personal access tokens (scope 'repo').${CL}" + echo -e "${YW}Skip this to authenticate later inside the container with 'gh auth login'.${CL}" + read -rsp " GitHub PAT (Enter to skip): " -t 120 var_gh_token || var_gh_token="" + echo "" +fi + export var_hostname var_projects_mode var_projects_storage var_projects_size var_gh_token function update_script() { diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 4eba34b6bf..4496a0e68b 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -80,7 +80,7 @@ "label": "GitHub Token", "type": "password", "secret": true, - "help": "Optional GitHub PAT; when empty, authenticate later with 'gh auth login' inside the container" + "help": "Optional GitHub Personal Access Token: create it at github.com -> Settings -> Developer settings -> Personal access tokens (scope 'repo'). When empty, authenticate later with 'gh auth login' inside the container" } ] } From cd8e2616fe148a22f23de50499dd7f0cb49afdad Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 13:41:27 +0100 Subject: [PATCH 04/19] fix: poll mountpoint activation after reboot instead of pct wait --- ct/gentle-shell.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index a32c987b80..9aa05ef942 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -96,7 +96,10 @@ if [[ "${var_projects_mode}" == "external" ]]; then pct set "${CTID}" -mp0 "${var_projects_storage}:${var_projects_size},mp=/mnt/projects" if ! pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then pct reboot "${CTID}" - pct wait "${CTID}" running + for _ in {1..30}; do + pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null && break + sleep 2 + done fi if ! pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then msg_error "Projects mountpoint on '${var_projects_storage}' did not activate; check the container config." From 1573d0ca13f3dd19fa10c1fd00b234bd596453d6 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 17:38:55 +0100 Subject: [PATCH 05/19] docs: state that provider API keys are configured in the first-launch setup --- json/gentle-shell.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 4496a0e68b..7ea932e460 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -35,7 +35,7 @@ }, "notes": [ { - "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its setup completes on first launch. Projects live in /root/projects.", + "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its first-launch setup asks for your provider API keys and keeps them inside the container. Projects live in /root/projects.", "type": "info" }, { From c8083202c3ce75022a327af76eed88aff27a0fca Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 17:47:41 +0100 Subject: [PATCH 06/19] feat: raise the minimum RAM to 4 GB for the coding agent --- ct/gentle-shell.sh | 2 +- json/gentle-shell.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 9aa05ef942..bf0f7e78fc 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -10,7 +10,7 @@ source "$_cs_boot" 2>/dev/null || source <(curl -fsSL "${COMMUNITY_SCRIPTS_CORE_ APP="gentle-shell" var_tags="${var_tags:-development;ai;coding-agent}" var_cpu="${var_cpu:-2}" -var_ram="${var_ram:-2048}" +var_ram="${var_ram:-4096}" var_disk="${var_disk:-10}" var_os="${var_os:-debian}" var_version="${var_version:-13}" diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 7ea932e460..194b4e691f 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -22,7 +22,7 @@ "script": "ct/gentle-shell.sh", "resources": { "cpu": 2, - "ram": 2048, + "ram": 4096, "hdd": 10, "os": "Debian", "version": "13" From 4ae2f6c12f8ad9257299a2df53b3ab849e6dc5c5 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 19:53:33 +0100 Subject: [PATCH 07/19] feat: pick an existing host directory or Proxmox storage for projects --- ct/gentle-shell.sh | 100 ++++++++++++++++++++++++++++++++++++++--- json/gentle-shell.json | 11 +++-- 2 files changed, 102 insertions(+), 9 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index bf0f7e78fc..c9e225c0b7 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -20,6 +20,7 @@ var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issu var_hostname="${var_hostname:-}" var_projects_mode="${var_projects_mode:-}" +var_projects_path="${var_projects_path:-}" var_projects_storage="${var_projects_storage:-}" var_projects_size="${var_projects_size:-}" var_gh_token="${var_gh_token:-}" @@ -35,17 +36,63 @@ fi var_hostname="${var_hostname:-gentle-shell}" if [[ -z "${var_projects_mode}" ]]; then - read -rp " Store projects [1] inside the LXC disk or [2] on an external Proxmox mountpoint (default: 1): " -t 60 var_projects_mode || var_projects_mode="1" + read -rp " Store projects [1] inside the LXC disk or [2] on existing storage (default: 1): " -t 60 var_projects_mode || var_projects_mode="1" fi case "${var_projects_mode}" in - 2 | external) var_projects_mode="external" ;; + 2 | external | bind | select) var_projects_mode="select" ;; *) var_projects_mode="internal" ;; esac -if [[ "${var_projects_mode}" == "external" ]]; then - if [[ -z "${var_projects_storage}" ]]; then - read -rp " Proxmox storage for the projects mountpoint (default: local-lvm): " -t 60 var_projects_storage || var_projects_storage="" +if [[ "${var_projects_mode}" == "select" ]]; then + if [[ -n "${var_projects_path}" ]]; then + var_projects_mode="bind" + elif [[ -n "${var_projects_storage}" ]]; then + var_projects_mode="external" + else + mapfile -t _proj_mounts < <( + findmnt -rno TARGET,FSTYPE 2>/dev/null | + awk '$2 == "ext4" || $2 == "xfs" || $2 == "btrfs" {print $1}' | + grep -Ev '^/(boot|dev|etc|proc|root|run|sys|tmp|usr|var)(/|$)' + ) + mapfile -t _proj_storages < <(pvesm status -content rootdir 2>/dev/null | awk 'NR > 1 {print $1}') + _proj_options=() + echo -e "${INFO}${YW}Available storage for projects:${CL}" + for _proj_entry in "${_proj_mounts[@]}"; do + [[ -n "${_proj_entry}" ]] || continue + _proj_options+=("bind:${_proj_entry}") + echo -e " ${BGN}[${#_proj_options[@]}]${CL} ${_proj_entry} ${YW}(existing host directory)${CL}" + done + for _proj_entry in "${_proj_storages[@]}"; do + [[ -n "${_proj_entry}" ]] || continue + _proj_options+=("storage:${_proj_entry}") + echo -e " ${BGN}[${#_proj_options[@]}]${CL} ${_proj_entry} ${YW}(new Proxmox volume)${CL}" + done + if (( ${#_proj_options[@]} == 0 )); then + echo -e "${INFO}${YW}No storage found; projects stay on the LXC disk.${CL}" + var_projects_mode="internal" + else + read -rp " Select storage [1-${#_proj_options[@]}] (default: 1): " -t 60 _proj_choice || _proj_choice="" + _proj_choice="${_proj_choice:-1}" + if ! [[ "${_proj_choice}" =~ ^[0-9]+$ ]] || (( _proj_choice < 1 || _proj_choice > ${#_proj_options[@]} )); then + msg_error "Invalid storage selection '${_proj_choice}'!" + exit 1 + fi + _proj_entry="${_proj_options[$((_proj_choice - 1))]}" + var_projects_mode="${_proj_entry%%:*}" + if [[ "${var_projects_mode}" == "bind" ]]; then + var_projects_path="${_proj_entry#bind:}" + read -rp " Subdirectory inside ${var_projects_path} (empty to use it directly): " -t 60 _proj_sub || _proj_sub="" + if [[ -n "${_proj_sub}" ]]; then + var_projects_path="${var_projects_path%/}/${_proj_sub#/}" + fi + else + var_projects_storage="${_proj_entry#storage:}" + fi + fi fi +fi + +if [[ "${var_projects_mode}" == "external" ]]; then var_projects_storage="${var_projects_storage:-local-lvm}" if ! pvesm status -content rootdir 2>/dev/null | awk 'NR>1 {print $1}' | grep -qx "${var_projects_storage}"; then msg_error "Storage '${var_projects_storage}' does not exist or cannot hold container mountpoints!" @@ -57,6 +104,20 @@ if [[ "${var_projects_mode}" == "external" ]]; then var_projects_size="${var_projects_size:-10}" fi +if [[ "${var_projects_mode}" == "bind" ]]; then + mkdir -p "${var_projects_path}" + if [[ ! -d "${var_projects_path}" ]]; then + msg_error "Directory '${var_projects_path}' does not exist on this Proxmox host!" + exit 1 + fi + if ! mountpoint -q "${var_projects_path}"; then + echo -e "${INFO}${YW}Note: ${var_projects_path} is not a mountpoint, so it lives on the host root filesystem.${CL}" + fi + if awk -v p="${var_projects_path}" '$1 == "path" && $2 == p {found = 1} END {exit !found}' /etc/pve/storage.cfg 2>/dev/null; then + echo -e "${INFO}${YW}Note: ${var_projects_path} is a Proxmox storage root. PVE keeps its own directories there, so a subdirectory is safer.${CL}" + fi +fi + if [[ -z "${var_gh_token}" ]]; then echo -e "${INFO}${YW}GitHub account (optional): to authenticate now, create a Personal Access Token at${CL}" echo -e "${YW}github.com -> Settings -> Developer settings -> Personal access tokens (scope 'repo').${CL}" @@ -65,7 +126,7 @@ if [[ -z "${var_gh_token}" ]]; then echo "" fi -export var_hostname var_projects_mode var_projects_storage var_projects_size var_gh_token +export var_hostname var_projects_mode var_projects_path var_projects_storage var_projects_size var_gh_token function update_script() { header_info @@ -109,6 +170,33 @@ if [[ "${var_projects_mode}" == "external" ]]; then msg_ok "Attached Projects Volume" fi +if [[ "${var_projects_mode}" == "bind" ]]; then + msg_info "Attaching Projects Directory (${var_projects_path})" + pct set "${CTID}" -mp0 "${var_projects_path},mp=/mnt/projects" + _proj_ready=false + if pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then + _proj_ready=true + else + pct reboot "${CTID}" + for _ in {1..30}; do + if pct exec "${CTID}" -- mountpoint -q /mnt/projects 2>/dev/null; then + _proj_ready=true + break + fi + sleep 2 + done + fi + if [[ "${_proj_ready}" == "false" ]]; then + msg_error "Projects directory '${var_projects_path}' did not mount; check the container config." + exit 1 + fi + if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then + echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 ${var_projects_path}' on the Proxmox host.${CL}" + fi + pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects + msg_ok "Attached Projects Directory" +fi + description msg_ok "Completed Successfully!\n" diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 194b4e691f..95bd023726 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -35,7 +35,7 @@ }, "notes": [ { - "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its first-launch setup asks for your provider API keys and keeps them inside the container. Projects live in /root/projects.", + "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its first-launch setup asks for your provider API keys and keeps them inside the container. Projects live in /root/projects, and a host directory mounted there needs uid 100000 ownership inside an unprivileged container.", "type": "info" }, { @@ -59,8 +59,13 @@ "name": "var_projects_mode", "label": "Projects Storage", "type": "text", - "default": "internal", - "help": "internal = /root/projects on the LXC disk; external = a new mountpoint on a Proxmox storage" + "help": "internal = /root/projects on the LXC disk; select = pick a host directory (bind mount) or a Proxmox storage (new volume) from a menu" + }, + { + "name": "var_projects_path", + "label": "Host Directory (bind mount)", + "type": "text", + "help": "Existing host path to mount as /root/projects, e.g. /mnt/disco/projects; used when Projects Storage is bind" }, { "name": "var_projects_storage", From 88af4024cf07e34b2eaae776201d02b6a15fc81f Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 20:05:50 +0100 Subject: [PATCH 08/19] fix: exclude system mounts, map storage selection to external mode, guard path input --- ct/gentle-shell.sh | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index c9e225c0b7..05d55d2015 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -24,6 +24,7 @@ var_projects_path="${var_projects_path:-}" var_projects_storage="${var_projects_storage:-}" var_projects_size="${var_projects_size:-}" var_gh_token="${var_gh_token:-}" +_proj_new_dir="" header_info "$APP" variables @@ -52,7 +53,7 @@ if [[ "${var_projects_mode}" == "select" ]]; then mapfile -t _proj_mounts < <( findmnt -rno TARGET,FSTYPE 2>/dev/null | awk '$2 == "ext4" || $2 == "xfs" || $2 == "btrfs" {print $1}' | - grep -Ev '^/(boot|dev|etc|proc|root|run|sys|tmp|usr|var)(/|$)' + grep -Ev '^/($|boot|dev|etc|proc|root|run|sys|tmp|usr|var)' ) mapfile -t _proj_storages < <(pvesm status -content rootdir 2>/dev/null | awk 'NR > 1 {print $1}') _proj_options=() @@ -78,14 +79,22 @@ if [[ "${var_projects_mode}" == "select" ]]; then exit 1 fi _proj_entry="${_proj_options[$((_proj_choice - 1))]}" - var_projects_mode="${_proj_entry%%:*}" - if [[ "${var_projects_mode}" == "bind" ]]; then + if [[ "${_proj_entry}" == bind:* ]]; then + var_projects_mode="bind" var_projects_path="${_proj_entry#bind:}" read -rp " Subdirectory inside ${var_projects_path} (empty to use it directly): " -t 60 _proj_sub || _proj_sub="" + _proj_sub="${_proj_sub#/}" + _proj_sub="${_proj_sub%/}" if [[ -n "${_proj_sub}" ]]; then - var_projects_path="${var_projects_path%/}/${_proj_sub#/}" + if [[ "${_proj_sub}" == *..* || "${_proj_sub}" == *,* ]]; then + msg_error "Invalid subdirectory name '${_proj_sub}'!" + exit 1 + fi + var_projects_path="${var_projects_path%/}/${_proj_sub}" + _proj_new_dir=true fi else + var_projects_mode="external" var_projects_storage="${_proj_entry#storage:}" fi fi @@ -105,17 +114,30 @@ if [[ "${var_projects_mode}" == "external" ]]; then fi if [[ "${var_projects_mode}" == "bind" ]]; then - mkdir -p "${var_projects_path}" + case "${var_projects_path}" in + / | /boot* | /dev* | /etc* | /proc* | /root* | /run* | /sys* | /tmp* | /usr* | /var*) + msg_error "'${var_projects_path}' is a host system path and cannot hold projects!" + exit 1 + ;; + esac + if [[ "${var_projects_path}" == *,* ]]; then + msg_error "Directory paths containing commas are not supported by Proxmox mountpoints!" + exit 1 + fi + if [[ -n "${_proj_new_dir:-}" ]]; then + mkdir -p "${var_projects_path}" + fi if [[ ! -d "${var_projects_path}" ]]; then msg_error "Directory '${var_projects_path}' does not exist on this Proxmox host!" exit 1 fi + if awk -v p="${var_projects_path}" '$1 == "path" && $2 == p {found = 1} END {exit !found}' /etc/pve/storage.cfg 2>/dev/null; then + msg_error "'${var_projects_path}' is a Proxmox storage root; choose a subdirectory inside it instead!" + exit 1 + fi if ! mountpoint -q "${var_projects_path}"; then echo -e "${INFO}${YW}Note: ${var_projects_path} is not a mountpoint, so it lives on the host root filesystem.${CL}" fi - if awk -v p="${var_projects_path}" '$1 == "path" && $2 == p {found = 1} END {exit !found}' /etc/pve/storage.cfg 2>/dev/null; then - echo -e "${INFO}${YW}Note: ${var_projects_path} is a Proxmox storage root. PVE keeps its own directories there, so a subdirectory is safer.${CL}" - fi fi if [[ -z "${var_gh_token}" ]]; then @@ -191,7 +213,7 @@ if [[ "${var_projects_mode}" == "bind" ]]; then exit 1 fi if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then - echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 ${var_projects_path}' on the Proxmox host.${CL}" + echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" fi pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects msg_ok "Attached Projects Directory" From 572ba2a44f64ebd78799a2c66f0309e273ec90c7 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 20:10:28 +0100 Subject: [PATCH 09/19] fix: create the projects directory only when its parent exists --- ct/gentle-shell.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 05d55d2015..35332986ba 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -24,7 +24,6 @@ var_projects_path="${var_projects_path:-}" var_projects_storage="${var_projects_storage:-}" var_projects_size="${var_projects_size:-}" var_gh_token="${var_gh_token:-}" -_proj_new_dir="" header_info "$APP" variables @@ -91,7 +90,6 @@ if [[ "${var_projects_mode}" == "select" ]]; then exit 1 fi var_projects_path="${var_projects_path%/}/${_proj_sub}" - _proj_new_dir=true fi else var_projects_mode="external" @@ -124,7 +122,7 @@ if [[ "${var_projects_mode}" == "bind" ]]; then msg_error "Directory paths containing commas are not supported by Proxmox mountpoints!" exit 1 fi - if [[ -n "${_proj_new_dir:-}" ]]; then + if [[ ! -d "${var_projects_path}" && -d "$(dirname "${var_projects_path}")" ]]; then mkdir -p "${var_projects_path}" fi if [[ ! -d "${var_projects_path}" ]]; then From 9ab763a28b136fd2568059004257fa5147c234dc Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 21:07:37 +0100 Subject: [PATCH 10/19] fix: anchor the system path guard and validate subdirectory segments --- ct/gentle-shell.sh | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 35332986ba..f422833733 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -85,10 +85,13 @@ if [[ "${var_projects_mode}" == "select" ]]; then _proj_sub="${_proj_sub#/}" _proj_sub="${_proj_sub%/}" if [[ -n "${_proj_sub}" ]]; then - if [[ "${_proj_sub}" == *..* || "${_proj_sub}" == *,* ]]; then - msg_error "Invalid subdirectory name '${_proj_sub}'!" - exit 1 - fi + IFS='/' read -ra _proj_parts <<<"${_proj_sub}" + for _proj_part in "${_proj_parts[@]}"; do + if [[ -z "${_proj_part}" || "${_proj_part}" == "." || "${_proj_part}" == ".." ]]; then + msg_error "Invalid subdirectory name '${_proj_sub}'!" + exit 1 + fi + done var_projects_path="${var_projects_path%/}/${_proj_sub}" fi else @@ -113,7 +116,7 @@ fi if [[ "${var_projects_mode}" == "bind" ]]; then case "${var_projects_path}" in - / | /boot* | /dev* | /etc* | /proc* | /root* | /run* | /sys* | /tmp* | /usr* | /var*) + / | /boot | /boot/* | /dev | /dev/* | /etc | /etc/* | /proc | /proc/* | /root | /root/* | /run | /run/* | /sys | /sys/* | /tmp | /tmp/* | /usr | /usr/* | /var | /var/*) msg_error "'${var_projects_path}' is a host system path and cannot hold projects!" exit 1 ;; From 284d9a43a00beba07182bc06d2da66732962f796 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 21:14:23 +0100 Subject: [PATCH 11/19] fix: restore recursive directory creation and anchor the mount filter boundary --- ct/gentle-shell.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index f422833733..52d96eb07e 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -52,7 +52,7 @@ if [[ "${var_projects_mode}" == "select" ]]; then mapfile -t _proj_mounts < <( findmnt -rno TARGET,FSTYPE 2>/dev/null | awk '$2 == "ext4" || $2 == "xfs" || $2 == "btrfs" {print $1}' | - grep -Ev '^/($|boot|dev|etc|proc|root|run|sys|tmp|usr|var)' + grep -Ev '^/($|(boot|dev|etc|proc|root|run|sys|tmp|usr|var)(/|$))' ) mapfile -t _proj_storages < <(pvesm status -content rootdir 2>/dev/null | awk 'NR > 1 {print $1}') _proj_options=() @@ -125,7 +125,7 @@ if [[ "${var_projects_mode}" == "bind" ]]; then msg_error "Directory paths containing commas are not supported by Proxmox mountpoints!" exit 1 fi - if [[ ! -d "${var_projects_path}" && -d "$(dirname "${var_projects_path}")" ]]; then + if [[ ! -d "${var_projects_path}" ]]; then mkdir -p "${var_projects_path}" fi if [[ ! -d "${var_projects_path}" ]]; then From ede998e7e53cf457dce848d7c69cb3e8cdb16041 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Wed, 18 Nov 2026 21:36:17 +0100 Subject: [PATCH 12/19] feat: list ZFS host mounts in the projects storage menu --- ct/gentle-shell.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 52d96eb07e..9566609672 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -51,7 +51,7 @@ if [[ "${var_projects_mode}" == "select" ]]; then else mapfile -t _proj_mounts < <( findmnt -rno TARGET,FSTYPE 2>/dev/null | - awk '$2 == "ext4" || $2 == "xfs" || $2 == "btrfs" {print $1}' | + awk '$2 ~ /^(ext4|xfs|btrfs|zfs)$/ {print $1}' | grep -Ev '^/($|(boot|dev|etc|proc|root|run|sys|tmp|usr|var)(/|$))' ) mapfile -t _proj_storages < <(pvesm status -content rootdir 2>/dev/null | awk 'NR > 1 {print $1}') From 1af8a12de7d972b9a099133b8d1d2029fcddaa65 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Thu, 19 Nov 2026 09:06:23 +0100 Subject: [PATCH 13/19] fix: keep explicit projects modes and replace the projects directory before linking --- ct/gentle-shell.sh | 20 +++++++++++++++++--- install/gentle-shell-install.sh | 2 +- json/gentle-shell.json | 2 +- 3 files changed, 19 insertions(+), 5 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 9566609672..cfdf193012 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -39,7 +39,15 @@ if [[ -z "${var_projects_mode}" ]]; then read -rp " Store projects [1] inside the LXC disk or [2] on existing storage (default: 1): " -t 60 var_projects_mode || var_projects_mode="1" fi case "${var_projects_mode}" in - 2 | external | bind | select) var_projects_mode="select" ;; + 2 | select) var_projects_mode="select" ;; + external) var_projects_mode="external" ;; + bind) + if [[ -z "${var_projects_path}" ]]; then + msg_error "var_projects_path is required for bind mode!" + exit 1 + fi + var_projects_mode="bind" + ;; *) var_projects_mode="internal" ;; esac @@ -189,7 +197,10 @@ if [[ "${var_projects_mode}" == "external" ]]; then msg_error "Projects mountpoint on '${var_projects_storage}' did not activate; check the container config." exit 1 fi - pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects + if ! pct exec "${CTID}" -- sh -c 'rm -rf /root/projects && ln -sfn /mnt/projects /root/projects'; then + msg_error "Failed to link /root/projects to the projects volume!" + exit 1 + fi msg_ok "Attached Projects Volume" fi @@ -216,7 +227,10 @@ if [[ "${var_projects_mode}" == "bind" ]]; then if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" fi - pct exec "${CTID}" -- ln -sfn /mnt/projects /root/projects + if ! pct exec "${CTID}" -- sh -c 'rm -rf /root/projects && ln -sfn /mnt/projects /root/projects'; then + msg_error "Failed to link /root/projects to the projects directory!" + exit 1 + fi msg_ok "Attached Projects Directory" fi diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh index d02ea9e9f4..0fc69acf75 100644 --- a/install/gentle-shell-install.sh +++ b/install/gentle-shell-install.sh @@ -31,7 +31,7 @@ if [[ -n "${var_gh_token:-}" ]]; then msg_ok "Authenticated GitHub CLI" fi -if [[ "${var_projects_mode:-internal}" != "external" ]]; then +if [[ "${var_projects_mode:-internal}" == "internal" ]]; then mkdir -p /root/projects fi diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 95bd023726..d14b81f1ec 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -59,7 +59,7 @@ "name": "var_projects_mode", "label": "Projects Storage", "type": "text", - "help": "internal = /root/projects on the LXC disk; select = pick a host directory (bind mount) or a Proxmox storage (new volume) from a menu" + "help": "internal = /root/projects on the LXC disk; external = new volume on a Proxmox storage (default local-lvm); bind = host directory from var_projects_path; select = menu of both" }, { "name": "var_projects_path", From 9c1ad3ff60faa5e12ab11b2a7f3b539417d53e1f Mon Sep 17 00:00:00 2001 From: jmoredev Date: Thu, 19 Nov 2026 12:56:48 +0100 Subject: [PATCH 14/19] fix: gate prompts to the PVE host and add key-based SSH access --- ct/gentle-shell.sh | 55 +++++++++++++++++++++++++-------- install/gentle-shell-install.sh | 9 ++++++ json/gentle-shell.json | 10 ++++-- 3 files changed, 59 insertions(+), 15 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index cfdf193012..9f75a0a8e9 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -24,12 +24,21 @@ var_projects_path="${var_projects_path:-}" var_projects_storage="${var_projects_storage:-}" var_projects_size="${var_projects_size:-}" var_gh_token="${var_gh_token:-}" +var_authorized_key="${var_authorized_key:-}" header_info "$APP" variables color catch_errors +_cs_in_container="$(detect_lxc_platform 2>/dev/null)" +if [[ "${_cs_in_container}" != "container" && "${_cs_in_container}" != "incus-container" ]]; then + +if [[ "${var_projects_mode}" == "bind" && -z "${var_projects_path}" ]]; then + msg_error "var_projects_path is required for bind mode!" + exit 1 +fi + if [[ -z "${var_hostname}" ]]; then read -rp " Machine name for Herdr (default: gentle-shell): " -t 60 var_hostname || var_hostname="" fi @@ -42,10 +51,6 @@ case "${var_projects_mode}" in 2 | select) var_projects_mode="select" ;; external) var_projects_mode="external" ;; bind) - if [[ -z "${var_projects_path}" ]]; then - msg_error "var_projects_path is required for bind mode!" - exit 1 - fi var_projects_mode="bind" ;; *) var_projects_mode="internal" ;; @@ -123,18 +128,20 @@ if [[ "${var_projects_mode}" == "external" ]]; then fi if [[ "${var_projects_mode}" == "bind" ]]; then + var_projects_path="$(realpath -m "${var_projects_path}")" + if [[ "${var_projects_path}" == *,* ]]; then + msg_error "Directory paths containing commas are not supported by Proxmox mountpoints!" + exit 1 + fi case "${var_projects_path}" in / | /boot | /boot/* | /dev | /dev/* | /etc | /etc/* | /proc | /proc/* | /root | /root/* | /run | /run/* | /sys | /sys/* | /tmp | /tmp/* | /usr | /usr/* | /var | /var/*) msg_error "'${var_projects_path}' is a host system path and cannot hold projects!" exit 1 ;; esac - if [[ "${var_projects_path}" == *,* ]]; then - msg_error "Directory paths containing commas are not supported by Proxmox mountpoints!" - exit 1 - fi if [[ ! -d "${var_projects_path}" ]]; then mkdir -p "${var_projects_path}" + _proj_created="yes" fi if [[ ! -d "${var_projects_path}" ]]; then msg_error "Directory '${var_projects_path}' does not exist on this Proxmox host!" @@ -149,6 +156,17 @@ if [[ "${var_projects_mode}" == "bind" ]]; then fi fi +if [[ -z "${var_authorized_key}" ]]; then + echo -e "${INFO}${YW}SSH access (recommended): paste your public key, e.g. the contents of${CL}" + echo -e "${YW}~/.ssh/id_ed25519.pub on your desktop. The container accepts key-based SSH only${CL}" + echo -e "${YW}(no root password login), and Herdr uses this key to connect to it.${CL}" + read -rp " SSH public key (Enter to skip): " -t 120 var_authorized_key || var_authorized_key="" +fi +if [[ -n "${var_authorized_key}" && ! "${var_authorized_key}" =~ ^(ssh-|ecdsa-|sk-) ]]; then + msg_error "var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!" + exit 1 +fi + if [[ -z "${var_gh_token}" ]]; then echo -e "${INFO}${YW}GitHub account (optional): to authenticate now, create a Personal Access Token at${CL}" echo -e "${YW}github.com -> Settings -> Developer settings -> Personal access tokens (scope 'repo').${CL}" @@ -157,7 +175,9 @@ if [[ -z "${var_gh_token}" ]]; then echo "" fi -export var_hostname var_projects_mode var_projects_path var_projects_storage var_projects_size var_gh_token +export var_hostname var_projects_mode var_projects_path var_projects_storage var_projects_size var_authorized_key var_gh_token + +fi function update_script() { header_info @@ -197,7 +217,7 @@ if [[ "${var_projects_mode}" == "external" ]]; then msg_error "Projects mountpoint on '${var_projects_storage}' did not activate; check the container config." exit 1 fi - if ! pct exec "${CTID}" -- sh -c 'rm -rf /root/projects && ln -sfn /mnt/projects /root/projects'; then + if ! pct exec "${CTID}" -- sh -c 'if [ -L /root/projects ]; then rm -f /root/projects; elif [ -d /root/projects ]; then rmdir /root/projects 2>/dev/null || exit 1; fi && ln -sfn /mnt/projects /root/projects'; then msg_error "Failed to link /root/projects to the projects volume!" exit 1 fi @@ -225,9 +245,18 @@ if [[ "${var_projects_mode}" == "bind" ]]; then exit 1 fi if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then - echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" + if [[ "${_proj_created:-}" == "yes" ]]; then + msg_info "Fixing ownership of ${var_projects_path}" + chown -R 100000:100000 "${var_projects_path}" + msg_ok "Fixed ownership" + if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then + echo -e "${INFO}${YW}Warning: the projects directory is still not writable inside the container.${CL}" + fi + else + echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" + fi fi - if ! pct exec "${CTID}" -- sh -c 'rm -rf /root/projects && ln -sfn /mnt/projects /root/projects'; then + if ! pct exec "${CTID}" -- sh -c 'if [ -L /root/projects ]; then rm -f /root/projects; elif [ -d /root/projects ]; then rmdir /root/projects 2>/dev/null || exit 1; fi && ln -sfn /mnt/projects /root/projects'; then msg_error "Failed to link /root/projects to the projects directory!" exit 1 fi @@ -238,4 +267,4 @@ description msg_ok "Completed Successfully!\n" echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}" -echo -e "${INFO}${YW}Connect via SSH (root) and run 'gentle-shell'; projects live in /root/projects.${CL}" +echo -e "${INFO}${YW}Connect via SSH as root (key-based) and run 'gentle-shell'; projects live in /root/projects.${CL}" diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh index 0fc69acf75..ddc75f1921 100644 --- a/install/gentle-shell-install.sh +++ b/install/gentle-shell-install.sh @@ -31,6 +31,15 @@ if [[ -n "${var_gh_token:-}" ]]; then msg_ok "Authenticated GitHub CLI" fi +if [[ -n "${var_authorized_key:-}" ]]; then + msg_info "Installing SSH Access Key" + mkdir -p /root/.ssh + chmod 700 /root/.ssh + printf '%s\n' "${var_authorized_key}" >> /root/.ssh/authorized_keys + chmod 600 /root/.ssh/authorized_keys + msg_ok "Installed SSH Access Key" +fi + if [[ "${var_projects_mode:-internal}" == "internal" ]]; then mkdir -p /root/projects fi diff --git a/json/gentle-shell.json b/json/gentle-shell.json index d14b81f1ec..1ccf542908 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -35,11 +35,11 @@ }, "notes": [ { - "text": "gentle-shell is a terminal application: connect via SSH (root) and run 'gentle-shell'; its first-launch setup asks for your provider API keys and keeps them inside the container. Projects live in /root/projects, and a host directory mounted there needs uid 100000 ownership inside an unprivileged container.", + "text": "gentle-shell is a terminal application: connect via SSH as root (key-based, no password login) and run 'gentle-shell'; first-launch setup asks for your provider API keys and keeps them inside the container.", "type": "info" }, { - "text": "To use it as a Herdr dev server, add this container to ~/.ssh/config on your desktop machine (Host , User root) and select it with Add Machine in Herdr.", + "text": "To use it as a Herdr remote machine, add it to ~/.ssh/config (Host , User root) and use Add Machine; Herdr connects with an SSH key, so pass var_authorized_key or the SSH Authorized Key option.", "type": "info" }, { @@ -55,6 +55,12 @@ "default": "gentle-shell", "help": "Container hostname; Herdr shows it as the remote machine name" }, + { + "name": "var_authorized_key", + "label": "SSH Public Key", + "type": "text", + "help": "Contents of your ~/.ssh/id_ed25519.pub (one line). The container accepts key-based SSH only; Herdr connects with this key. Skip to add it later inside /root/.ssh/authorized_keys" + }, { "name": "var_projects_mode", "label": "Projects Storage", From 276b3a17d7d5962721074cff8602bb1d87d6d6fb Mon Sep 17 00:00:00 2001 From: jmoredev Date: Thu, 19 Nov 2026 13:23:17 +0100 Subject: [PATCH 15/19] fix: guard authorized_keys append and polish access messaging --- ct/gentle-shell.sh | 13 ++++++++++--- install/gentle-shell-install.sh | 3 +++ json/gentle-shell.json | 2 +- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 9f75a0a8e9..4387fb8fff 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -247,10 +247,13 @@ if [[ "${var_projects_mode}" == "bind" ]]; then if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then if [[ "${_proj_created:-}" == "yes" ]]; then msg_info "Fixing ownership of ${var_projects_path}" - chown -R 100000:100000 "${var_projects_path}" + if ! chown -R 100000:100000 "${var_projects_path}"; then + msg_error "Failed to fix ownership of '${var_projects_path}'!" + exit 1 + fi msg_ok "Fixed ownership" if ! pct exec "${CTID}" -- sh -c 'touch /mnt/projects/.cs-write-test && rm -f /mnt/projects/.cs-write-test' 2>/dev/null; then - echo -e "${INFO}${YW}Warning: the projects directory is still not writable inside the container.${CL}" + echo -e "${INFO}${YW}Warning: the projects directory is still not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" fi else echo -e "${INFO}${YW}Warning: the projects directory is not writable inside the container. Run 'chown -R 100000:100000 \"${var_projects_path}\"' on the Proxmox host.${CL}" @@ -267,4 +270,8 @@ description msg_ok "Completed Successfully!\n" echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}" -echo -e "${INFO}${YW}Connect via SSH as root (key-based) and run 'gentle-shell'; projects live in /root/projects.${CL}" +if [[ -n "${var_authorized_key:-}" ]]; then + echo -e "${INFO}${YW}Connect via SSH as root (key-based) and run 'gentle-shell'; projects live in /root/projects.${CL}" +else + echo -e "${INFO}${YW}Connect via the Proxmox console or SSH (add a public key to /root/.ssh/authorized_keys) and run 'gentle-shell'; projects live in /root/projects.${CL}" +fi diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh index ddc75f1921..b9657b3fc5 100644 --- a/install/gentle-shell-install.sh +++ b/install/gentle-shell-install.sh @@ -35,6 +35,9 @@ if [[ -n "${var_authorized_key:-}" ]]; then msg_info "Installing SSH Access Key" mkdir -p /root/.ssh chmod 700 /root/.ssh + if [[ -s /root/.ssh/authorized_keys && -n "$(tail -c 1 /root/.ssh/authorized_keys)" ]]; then + printf '\n' >> /root/.ssh/authorized_keys + fi printf '%s\n' "${var_authorized_key}" >> /root/.ssh/authorized_keys chmod 600 /root/.ssh/authorized_keys msg_ok "Installed SSH Access Key" diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 1ccf542908..627bd723e9 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -39,7 +39,7 @@ "type": "info" }, { - "text": "To use it as a Herdr remote machine, add it to ~/.ssh/config (Host , User root) and use Add Machine; Herdr connects with an SSH key, so pass var_authorized_key or the SSH Authorized Key option.", + "text": "To use it as a Herdr remote machine, add it to ~/.ssh/config (Host , User root) and use Add Machine; Herdr connects with an SSH key, so pass var_authorized_key (SSH Public Key).", "type": "info" }, { From 0615a24e9687c1e146d686e59168c6b56a0a315e Mon Sep 17 00:00:00 2001 From: jmoredev Date: Thu, 19 Nov 2026 19:54:57 +0100 Subject: [PATCH 16/19] feat: expose the bundled Engram TUI on PATH --- install/gentle-shell-install.sh | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh index b9657b3fc5..09cc94bd49 100644 --- a/install/gentle-shell-install.sh +++ b/install/gentle-shell-install.sh @@ -25,6 +25,19 @@ msg_info "Installing gentle-shell (gentle-pi)" $STD npm install -g gentle-pi msg_ok "Installed gentle-shell" +cat <<'EOF' >/usr/local/bin/engram +#!/usr/bin/env sh +# Resolves the newest Engram core published by Gentle Shell into ~/.gentle-shell/runtime. +core=$(ls -1d "${HOME:-/root}"/.gentle-shell/runtime/engram-*/engram 2>/dev/null | sort -V | tail -1) +if [ -z "$core" ]; then + echo "engram: no Gentle Shell published core found." >&2 + echo "engram: start 'gentle-shell' once to publish the Engram core, then retry." >&2 + exit 1 +fi +exec "$core" "$@" +EOF +chmod 755 /usr/local/bin/engram + if [[ -n "${var_gh_token:-}" ]]; then msg_info "Authenticating GitHub CLI" printf '%s' "${var_gh_token}" | gh auth login --with-token From ccfb851a36bffb50bcc598d54c0a65f4273aacc6 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Fri, 20 Nov 2026 08:37:22 +0100 Subject: [PATCH 17/19] fix: fail the install when the SSH key cannot be written --- install/gentle-shell-install.sh | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/install/gentle-shell-install.sh b/install/gentle-shell-install.sh index 09cc94bd49..421779261a 100644 --- a/install/gentle-shell-install.sh +++ b/install/gentle-shell-install.sh @@ -46,13 +46,17 @@ fi if [[ -n "${var_authorized_key:-}" ]]; then msg_info "Installing SSH Access Key" - mkdir -p /root/.ssh - chmod 700 /root/.ssh + if ! mkdir -p /root/.ssh || ! chmod 700 /root/.ssh; then + msg_error "Failed to prepare /root/.ssh" + exit 1 + fi if [[ -s /root/.ssh/authorized_keys && -n "$(tail -c 1 /root/.ssh/authorized_keys)" ]]; then printf '\n' >> /root/.ssh/authorized_keys fi - printf '%s\n' "${var_authorized_key}" >> /root/.ssh/authorized_keys - chmod 600 /root/.ssh/authorized_keys + if ! printf '%s\n' "${var_authorized_key}" >> /root/.ssh/authorized_keys || ! chmod 600 /root/.ssh/authorized_keys; then + msg_error "Failed to write /root/.ssh/authorized_keys" + exit 1 + fi msg_ok "Installed SSH Access Key" fi From f131a99348c7b1a749f20701c51dedc66eea5ced Mon Sep 17 00:00:00 2001 From: jmoredev Date: Fri, 20 Nov 2026 08:44:01 +0100 Subject: [PATCH 18/19] chore: point var_testurl at the gentle-shell testing issue --- ct/gentle-shell.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 4387fb8fff..428e764ee7 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -16,7 +16,7 @@ var_os="${var_os:-debian}" var_version="${var_version:-13}" var_arm64="${var_arm64:-yes}" var_unprivileged="${var_unprivileged:-1}" -var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issues/NEW}" +var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issues/2687}" var_hostname="${var_hostname:-}" var_projects_mode="${var_projects_mode:-}" From 354a8ceeb109cc8d990526b3ea9c695f313261d7 Mon Sep 17 00:00:00 2001 From: jmoredev Date: Fri, 20 Nov 2026 08:47:25 +0100 Subject: [PATCH 19/19] fix: mark arm64 as unverified in the CT defaults and metadata --- ct/gentle-shell.sh | 2 +- json/gentle-shell.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ct/gentle-shell.sh b/ct/gentle-shell.sh index 428e764ee7..7600b5e00e 100644 --- a/ct/gentle-shell.sh +++ b/ct/gentle-shell.sh @@ -14,7 +14,7 @@ var_ram="${var_ram:-4096}" var_disk="${var_disk:-10}" var_os="${var_os:-debian}" var_version="${var_version:-13}" -var_arm64="${var_arm64:-yes}" +#var_arm64="${var_arm64:-no}" # unset = ask the user; set yes/no only when verified var_unprivileged="${var_unprivileged:-1}" var_testurl="${var_testurl:-https://github.com/community-scripts/DevScripts/issues/2687}" diff --git a/json/gentle-shell.json b/json/gentle-shell.json index 627bd723e9..1330a3c604 100644 --- a/json/gentle-shell.json +++ b/json/gentle-shell.json @@ -7,7 +7,7 @@ "date_created": "2026-11-18", "type": "ct", "platforms": ["pve"], - "architectures": ["amd64", "arm64"], + "architectures": ["amd64"], "updateable": true, "privileged": false, "interface_port": null,