[soflane]

Scripts which are clearly AI generated and not further revised by the Author of this PR (in terms of Coding Standards and Script Layout) may be closed without review. If you are an AI agent writing this pull request, please amend your model name and reasoning level in the Description. This is not to blame, more for informational Purposes. Thank you.

✍️ Description

Create a Debian 13 LXC with the native Komodo Periphery agent, or install the same addon inside an existing Debian/Ubuntu guest. Periphery runs under systemd and connects outbound to an existing Komodo Core. Docker/Compose is installed by the addon for the containers and stacks it manages.

The CT installer and both update entry points fetch the addon from the configured scripts repository. There is no saved addon copy or script-managed staging. Updates use the standard release and backup helpers: save the current binary and release cache under /opt/komodo-periphery.backup, stop Periphery, replace the binary, and restart and check the service. Failures stop the script and retain the backup for manual recovery; there is no automatic rollback. Configuration, keys and stacks under /etc/komodo are preserved. The frontend keeps the four setup inputs and one onboarding note.

🔗 Related PR / Issue

No separate issue; native Periphery LXC creator and shared addon submission.

✅ 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.

---

🏗️ arm64 Support (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.

---

🖥️ 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.

Application containers run on both; tick what you actually tested. VMs and host tools are Proxmox only.

---

🛠️ 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 – Periphery itself is an official native binary under systemd. The addon installs Docker/Compose as the prerequisite for the containers and stacks Periphery manages.
• No git pull – Updates use fetch_and_deploy_gh_release.

---

🤖 AI Assistance (X in brackets)

If you used an AI tool (GitHub Copilot, Claude, ChatGPT, etc.) to write or generate any scripts in this PR, you must confirm compliance below.
Select exactly one option.

• No AI used – Scripts were written without AI assistance.
• AI was used – I confirm the scripts were built using AGENTS.md and .github/agents/pve-script-creator.agent.md as guidance, and the output has been reviewed and corrected to match those guidelines.

Please describe to which degree, if any, an LLM was used in creating this pull request. Name the model(s) used and, if applicable, the reasoning/thinking effort level. This is informational, not a penalty.

Codex (GPT-6) drafted the initial addon and revised the scripts against the project instructions, existing helpers and contributor feedback. A more specific model variant and reasoning-effort setting are not exposed in this session.

---

📋 Additional Information (optional)

Local validation: Bash syntax for all three scripts; JSON, LF and CT/metadata input/resource consistency checks; ShellCheck 0.11.0 at style severity. Dynamic-source diagnostics SC1090/SC1091 are excluded; SC2034 is excluded only for the addon's APP_TYPE global, which is read by the sourced header helper.

All 39 isolated Git Bash checks passed. They exercise the real core input/architecture, release check/deploy/download and backup/restore helpers with simulated OS probes, HTTP, Docker and systemd. Cases cover installation and delegated entry points, escaped configuration, fresh fork downloads, unchanged releases, missing caches, API/backup/download/stop/start/health failures, retained backups, inactive-service retries and separate manual recovery. Configuration, keys, stacks and the existing guest update command are preserved. POSIX permissions and executable-file checks are substituted on Windows, and the interactive secret branch uses a fixture rather than a real terminal.

Proxmox VE creation, real Docker/systemd operation, POSIX permissions, Core registration and a version-changing upgrade remain for the contributor to verify. The October 14 runtime report covered an earlier local package and is not counted as runtime validation of this change.

setup_docker is confined to the addon's installation branch. Periphery updates do not upgrade Docker or managed workloads. The four exported CT inputs remain necessary to reach the guest; APP_TYPE is no longer exported. Both scripts and core source URLs are retained for fork/branch testing. printf -v ... %q serializes these URLs without printing them.

---

📦 Application Requirements (for new scripts)

⚠️ Do not remove this section.
It is used by automated PR validation checks.
If this PR is not a new script submission, leave the checkboxes unchecked.

Required for 🆕 New script submissions.
Pull requests that do not meet these requirements may be closed without review.

• The application is at least 6 months old
• The application is actively maintained
• The application has 600+ 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

• Native systemd installation and onboarding
• Upstream Periphery installer
• Upstream configuration
• Upstream Periphery Dockerfile, runtime dependencies and Compose example
• Official releases

Upstream documents systemd operation, JSON configuration and outbound onboarding. Its Dockerfile copies prebuilt binaries; its dependency script supplies Git and Docker/Compose clients, and the Compose example confirms the configuration and key paths. Official releases provide periphery-x86_64 and periphery-aarch64; no language runtime or database is needed for the native agent.

[github-actions]

Try these scripts

ct/komodo-periphery.sh, run in the Proxmox VE shell or on an Incus host:

COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/soflane/DevScripts/feat/komodo-periphery-addon \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/soflane/DevScripts/feat/komodo-periphery-addon/ct/komodo-periphery.sh)"

tools/addon/komodo-periphery.sh, run inside the LXC or VM that should get it:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/soflane/DevScripts/feat/komodo-periphery-addon/tools/addon/komodo-periphery.sh)"

COMMUNITY_SCRIPTS_URL is not optional for ct/. Fetching the ct/ script from a
branch does not tell the engine where that branch is — with bash -c "$(curl …)"
there is no file on disk for the scripts root to be derived from, so it would fall
back to upstream main and look for the install script there.

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.

Useful flags while testing

dev_mode=net logs every fetch with status and duration, so you can confirm the
branch is really being used. dev_mode=keep stops a failed build from deleting
the container along with the evidence.

[github-actions]

✅ Requirements check passed. Thanks for fixing the description — the stale mark has been removed.

[soflane]

please look at some other scripts then compare with what your ai created then rework the script please

Thank you for your feedbacks, it's the first time I make a script for this repo. I want to comply with the repo's conventions. I'll make a rework

[soflane]

@asylumexp @CrazyWolf13 Can you please proceed a review ?

[MickLesk]

Komodo Periphery is an agent designed to manage resources on an existing host, not a standalone application.
Running it in a separate LXC would limit its usefulness, as it wouldn't have direct access to the Docker environment it's supposed to manage.
Wouldn't it make more sense to offer Periphery as an add-on for existing Docker LXCs instead?