(airflow-steward) branch main updated: docs(secure-agent-setup): add Linux Mint 22 / Ubuntu Noble shortcut (#12)

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git


The following commit(s) were added to refs/heads/main by this push:
     new 7a19411  docs(secure-agent-setup): add Linux Mint 22 / Ubuntu Noble shortcut (#12)
7a19411 is described below

commit 7a1941122581224bdb310bae822a241d239833e7
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Wed Apr 29 15:52:20 2026 +0200

    docs(secure-agent-setup): add Linux Mint 22 / Ubuntu Noble shortcut (#12)
    
    The pinned bubblewrap (0.11.1) and socat (1.8.1.1) versions in
    `tools/agent-isolation/pinned-versions.toml` are the upstream
    releases that have aged past the framework's 7-day cooldown — they
    are NOT in Ubuntu Noble's main repos. Noble ships:
    
      bubblewrap 0.9.0  (0.9.0-1ubuntu0.1)
      socat      1.8.0.0 (1.8.0.0-4build3)
    
    Both pre-date the framework's pins by months and are well past the
    cooldown, so they're a legitimate adopter choice on Mint 22.
    Ubuntu 24.04 — but the framework's main install path documents the
    upstream pins, which leaves Mint/Noble adopters without a cl
    story.
    
    This commit adds a *Distro-specific shortcut* section under
    \`Install commands\` that:
    
    - Documents the apt-shipped versions and their \`apt_pin\` s
    - Calls out the trade-off explicitly (older feature set, but apt-
      managed security backports, no source build).
    - Notes that the framework's \`.claude/settings.json\` works
      unchanged — the sandbox API has been stable since bubblewr
      0.6.x.
    - Tells the user how to silence the drift the check script w
      report against the upstream pins (a \`pinned-versions.local.toml\`,
      matching Claude Code's own \`settings.local.json\` convent
    - Closes with the rationale for keeping this as a "shortcut" rather
      than the canonical path.
    
    No change to \`pinned-versions.toml\` itself — the framework
    default pin still tracks the upstream release stream, which is the
    right thing to track for the weekly check-tool-updates routi
    
    Generated-by: Claude Code (Claude Opus 4.7)
---
 secure-agent-setup.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/secure-agent-setup.md b/secure-agent-setup.md
index e6f8db7..4a8ed00 100644
--- a/secure-agent-setup.md
+++ b/secure-agent-setup.md
@@ -136,6 +136,53 @@ version, no pin enforced — Homebrew rolls forward, so the
 npm install -g --no-save @anthropic-ai/claude-code@2.1.117
 ```
 
+### Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble
+
+The pinned versions above (bubblewrap `0.11.1`, socat `1.8.1.1`) are
+the *upstream* releases that have aged past the framework's 7-day
+cooldown. **They are not in Ubuntu Noble's main repos** — Noble
+ships `bubblewrap 0.9.0` (`0.9.0-1ubuntu0.1`) and
+`socat 1.8.0.0` (`1.8.0.0-4build3`).
+
+Both Noble-shipped versions pre-date the framework's pins by months
+and are well past the 7-day cooldown, so they're a legitimate
+adopter choice on Mint 22.x / Ubuntu 24.04. The trade-off is the
+usual LTS one: older feature set, but no source build required,
+and security backports flow through Ubuntu's standard update
+channel.
+
+If you accept the trade-off, install via apt:
+
+```bash
+sudo apt-get update
+sudo apt-get install --no-install-recommends \
+    bubblewrap=0.9.0-1ubuntu0.1 \
+    socat=1.8.0.0-4build3
+```
+
+The framework's `.claude/settings.json` works unchanged — the
+sandbox flags don't depend on a specific bubblewrap version (the
+`denyRead`/`allowRead` API has been stable since `0.6.x`).
+
+The framework's `tools/agent-isolation/check-tool-updates.sh` will
+still report upstream `0.11.1` / `1.8.1.1` as the pinned versions —
+that's the manifest's view of what's *upstream-current*, not what
+your distro shipped. If you want to silence the drift, override the
+manifest locally with a `pinned-versions.local.toml` (gitignored)
+declaring the Noble versions; the script's manifest-precedence
+follows the same `*.local` convention as Claude Code's
+`settings.local.json`.
+
+> **Why this is documented as a separate "shortcut" rather than
+> the canonical path.** The framework's default pin tracks the
+> upstream release stream, not any specific distro. Adopters on
+> distros that ship recent versions (Arch, Fedora rolling, NixOS
+> on `nixos-unstable`) can install the upstream-pinned versions
+> directly from their package manager. Adopters on LTS distros
+> like Mint / Ubuntu Noble use this shortcut. The two paths
+> converge — once Noble's next LTS adopts a newer bubblewrap, this
+> section retires.
+
 ### Bumping a pinned version
 
 When an upstream release has aged past the 7-day cooldown and you