Skip to content

Add gentle-shell (AI coding-agent LXC dev server) - #2688

Closed
jmoredev wants to merge 19 commits into
community-scripts:mainfrom
jmoredev:feat-gentle-shell
Closed

jmoredev wants to merge 19 commits into
community-scripts:mainfrom
jmoredev:feat-gentle-shell

Conversation

@jmoredev

Copy link
Copy Markdown

✍️ Description

gentle-shell is a coding-agent workspace and TUI harness built for Pi (agent orchestration, ODD task tracking, Git diffs and persistent memory, driven from the terminal); this CT creates an LXC development server with Node 22, gentle-shell (npm gentle-pi), git and the GitHub CLI preinstalled, meant to be driven remotely from the Gentle Shell desktop app via Herdr. It deviates from the standard pattern by being SSH-first: since the base template clears the root password, the install optionally accepts var_authorized_key (an SSH public key) and installs it as the root user's authorized key, leaving the container immediately connectable as a remote machine. Its prompts are gated to the PVE/Incus host so the in-container update path stays non-interactive, and the bundled Engram TUI is exposed on PATH. Steps from the upstream npm package (Node 22, npm install -g gentle-pi). Tested on a real Proxmox VE 9.2.26 host: interactive and unattended install, bind-mount projects mode, in-container update and a full Herdr remote session with remote login.

AI-assisted (GLM-5.3 via the Gentle Shell / Pi harness, high reasoning) following AGENTS.md and the script-creator agent guidance, then reviewed and corrected against the project conventions.

🔗 Related PR / Issue

Link: Refs #2687

✅ Prerequisites (X in brackets)

  • Self-review completed – Code follows project standards.
  • Tested thoroughly – Changes work as expected.
  • No breaking changes – Existing functionality remains intact.
  • No security risks – No hardcoded secrets, unnecessary privilege escalations, or permission issues.

🧩 Script

Name: gentle-shell

Tool: AI coding-agent workspace and TUI harness for Pi: parallel coding agents, task tracking, Git diffs and persistent memory in one terminal. This CT provisions a ready-to-use LXC development server for it.

🗂️ Category (X in brackets)

  • CT – LXC container (ct/ + install/)
  • VM – Virtual machine (vm/)
  • Addon – tools/addon/
  • PVE Tool – tools/pve/
  • Other – path given in the Description

🖥️ Platform – tested on (X in brackets)

  • Proxmox VE – Created on a Proxmox VE host and the app works.
  • Incus – Created on an Incus host and the app works.

🏗️ Architecture (X in brackets)

  • arm64 supported - Tested and supported on arm64.
  • arm64 not tested - Assumed to work on arm64, but testing has not been done.
  • arm64 not supported - Confirmed upstream dependencies or binaries do not support arm64.

🛠️ Type of Change (X in brackets)

  • 🐞 Bug fix – Resolves an issue without breaking functionality.
  • ✨ New feature – Adds new, non-breaking functionality.
  • 💥 Breaking change – Alters existing functionality in a way that may require updates.
  • 🆕 New script – A fully functional and tested script or script set.
  • 🌍 Website update – Changes to website-related JSON files or metadata.
  • 🔧 Refactoring / Code Cleanup – Improves readability or maintainability without changing functionality.
  • 📝 Documentation update – Changes to README, AppName.md, CONTRIBUTING.md, or other docs.

🔍 Code & Security Review (X in brackets)

  • Follows CODE-AUDIT.md & CONTRIBUTING.md guidelines
  • Uses correct script structure (AppName.sh, AppName-install.sh, AppName.json)
  • No hardcoded credentials
  • No Docker / Docker Compose – The application is installed bare-metal; Docker is not used.
  • No git pull – Updates use fetch_and_deploy_gh_release, fetch_and_deploy_codeberg_release, fetch_and_deploy_gl_release, or fetch_and_deploy_from_url instead of git pull.

📋 Additional Information (optional)

The update path refreshes gentle-pi through npm (npm view gentle-pi version + npm install -g gentle-pi@<version>), which is upstream's own distribution channel. Testing feedback is collected in #2687 (var_testurl points there).


📦 Application Requirements (for new scripts)

  • The application is at least 6 months old
  • The application is actively maintained
  • The application has 1,000+ GitHub stars
  • Official release tarballs are published
  • I understand that not all scripts will be accepted due to various reasons and criteria by the community-scripts ORG

🌐 Source


🤖 AI Assistance (X in brackets)

Please describe to which degree, if any, an LLM was used in creating this pull request.

GLM-5.3 (via the Gentle Shell / Pi coding-agent harness), high reasoning, used to draft and iterate ct/gentle-shell.sh, install/gentle-shell-install.sh and json/gentle-shell.json against AGENTS.md, then manually reviewed and tested end-to-end on a real Proxmox VE 9.2.26 host (install, unattended install, update inside the container, SSH-key flow and a full Herdr remote session).

@jmoredev
jmoredev requested a review from a team as a code owner November 20, 2026 07:58
@github-actions

Copy link
Copy Markdown
Contributor

Try this branch

The engine and the scripts resolve independently, so this runs the changed
ct/ and install/ scripts against the production engine:

export COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/jmoredev/DevScripts/feat-gentle-shell
bash -c "$(curl -fsSL "$COMMUNITY_SCRIPTS_URL/ct/gentle-shell.sh")"

Both lines are needed. Without COMMUNITY_SCRIPTS_URL the engine falls back to
main, so curling the branch URL on its own gives you the ct/ script from
this PR and the install/ script from main. Frequently the one you meant to test.

The same command works on an Incus host: the engine detects the platform and
loads the matching backend, while the scripts still come from this branch.

Useful while testing

dev_mode=net logs every fetch with status and URL, which is the quickest way
to confirm the branch is really being used. dev_mode=keep stops a failed
build from deleting the container along with the evidence.

export COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/jmoredev/DevScripts/feat-gentle-shell
dev_mode=net,keep bash -c "$(curl -fsSL "$COMMUNITY_SCRIPTS_URL/ct/gentle-shell.sh")"
Against a core branch as well

Add COMMUNITY_SCRIPTS_CORE_URL=https://raw.githubusercontent.com/OWNER/core/BRANCH
to test an engine change at the same time. The two resolve independently.

@github-actions

Copy link
Copy Markdown
Contributor

Proxmox script test

@jmoredev ❌ 0/2 passed at 354a8ce

Script Platform Install Update Duration Detail
ct/gentle-shell.sh pve ❌ – 0m11s build exited 1: var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!
ct/gentle-shell.sh incus ❌ – 0m04s build exited 1: var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!
ct/gentle-shell.sh arm64 ❌ – 0m03s build exited 1: var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!

ARM64 (information only, not counted): 0/1 passed; failures there do not block this PR.

❌ ct/gentle-shell.sh (pve) — build log
curl: (22) The requested URL returned error: 404
curl: (22) The requested URL returned error: 404
   ______                                      _ __           _____           _       __
  / ____/___  ____ ___  ____ ___  __  ______  (_) /___  __   / ___/__________(_)___  / /______
 / /   / __ \/ __ `__ \/ __ `__ \/ / / / __ \/ / __/ / / /   \__ \/ ___/ ___/ / __ \/ __/ ___/
/ /___/ /_/ / / / / / / / / / / / /_/ / / / / / /_/ /_/ /   ___/ / /__/ /  / / /_/ / /_(__  )
\____/\____/_/ /_/ /_/_/ /_/ /_/\__,_/_/ /_/_/\__/\__, /   /____/\___/_/  /_/ .___/\__/____/
                                                 /____/                    /_/
  gentle-shell
  🔧  Dev mode: timing keep
  ── dev context ─────────────────────────────────────────────
  engine         prefetched → /dev/shm/cs-engine.OhFYjF
  engine url     https://raw.githubusercontent.com/community-scripts/core/main
  scripts root   none (remote)
  scripts url    http://10.99.0.1:18080/44698875957-1-pve-ct-gentle-shell-default
  app            gentle-shell (gentle-shell, type ?)
  platform       pve
  arch           amd64
  pve            9.2.26
  bash           5.2.37
  curl           8.14.1
  session        4a113266
  ────────────────────────────────────────────────────────────
  ✖️  var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!
❌ ct/gentle-shell.sh (incus) — build log
   ______                                      _ __           _____           _       __
  / ____/___  ____ ___  ____ ___  __  ______  (_) /___  __   / ___/__________(_)___  / /______
 / /   / __ \/ __ `__ \/ __ `__ \/ / / / __ \/ / __/ / / /   \__ \/ ___/ ___/ / __ \/ __/ ___/
/ /___/ /_/ / / / / / / / / / / / /_/ / / / / / /_/ /_/ /   ___/ / /__/ /  / / /_/ / /_(__  )
\____/\____/_/ /_/ /_/_/ /_/ /_/\__,_/_/ /_/_/\__/\__, /   /____/\___/_/  /_/ .___/\__/____/
                                                 /____/                    /_/
  gentle-shell
  🔧  Dev mode: timing keep
  ── dev context ─────────────────────────────────────────────
  engine         prefetched → /dev/shm/cs-engine.d4sCjk
  engine url     https://raw.githubusercontent.com/community-scripts/core/main
  scripts root   none (remote)
  scripts url    http://10.98.0.1:18080/44698875957-1-incus-ct-gentle-shell-default
  app            gentle-shell (gentle-shell, type ?)
  platform       incus
  arch           amd64
  bash           5.2.37
  curl           8.14.1
  session        56a39be5
  ────────────────────────────────────────────────────────────
  ✖️  var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!
❌ ct/gentle-shell.sh (arm64) — build log
   ______                                      _ __           _____           _       __
  / ____/___  ____ ___  ____ ___  __  ______  (_) /___  __   / ___/__________(_)___  / /______
 / /   / __ \/ __ `__ \/ __ `__ \/ / / / __ \/ / __/ / / /   \__ \/ ___/ ___/ / __ \/ __/ ___/
/ /___/ /_/ / / / / / / / / / / / /_/ / / / / / /_/ /_/ /   ___/ / /__/ /  / / /_/ / /_(__  )
\____/\____/_/ /_/ /_/_/ /_/ /_/\__,_/_/ /_/_/\__/\__, /   /____/\___/_/  /_/ .___/\__/____/
                                                 /____/                    /_/
  gentle-shell
  🔧  Dev mode: timing keep
  ── dev context ─────────────────────────────────────────────
  engine         prefetched → /dev/shm/cs-engine.T7U28a
  engine url     https://raw.githubusercontent.com/community-scripts/core/main
  scripts root   none (remote)
  scripts url    http://10.98.0.1:18080/44698875957-1-incus-ct-gentle-shell-default
  app            gentle-shell (gentle-shell, type ?)
  platform       incus
  arch           arm64
  bash           5.2.21
  curl           8.5.0
  session        a823caab
  ────────────────────────────────────────────────────────────
  ✖️  var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!

Full logs: workflow run (artifacts result-*). Comment /test to build again.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proxmox script test failed at 354a8ce:

  • ct/gentle-shell.sh (pve): build exited 1: var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!
  • ct/gentle-shell.sh (incus): build exited 1: var_authorized_key must be a public key (contents of ~/.ssh/id_ed25519.pub), not a private key!

Logs and details: test result. Push a fix, then ask for /test again.

@michelroegl-brunner

Copy link
Copy Markdown
Member

Nah, i wont add that. Sorry but that scipt is so of Standards and dose so much work in the /ct part, that this is bound to break.
We made the desicion that not every script is a good fit for our repo, and this is sadly one of them.

If you can do it in the install script and only do the update in the /ct script we might take a second look.

Also the whole storage selection part is just messy.

Our scripts are here to get a "One-Click" installer feel for our users. This one needs so much setup work that we are for sure getting one issue after another.

@jmoredev

Copy link
Copy Markdown
Author

Fair points, thanks for the quick look.

We'll rework it: the CT script goes back to the standard shape (defaults and update_script only), the SSH key setup moves into the install script, and the storage selection menus are dropped entirely (projects live in /root/projects, anyone wanting a host directory can add an mp0 bind mount from the Proxmox UI).

Will push the rework to this branch for another lab run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants