clauster 0.2.2__tar.gz → 0.3.0__tar.gz

{clauster-0.2.2 → clauster-0.3.0}/.bestpractices.json

@@ -114,7 +114,7 @@
   "vulnerabilities_fixed_60_days_status": "Met",
   "vulnerabilities_fixed_60_days_justification": "Renovate and GitHub security alerts surface dependency vulnerabilities, which are patched promptly (well within 60 days).",
   "vulnerabilities_critical_fixed_status": "Met",
-  "vulnerabilities_critical_fixed_justification": "No known unpatched vulnerabilities exist (OpenSSF Scorecard Vulnerabilities check scores 10/10).",
+  "vulnerabilities_critical_fixed_justification": "No known unpatched vulnerabilities exist; the OpenSSF Scorecard Vulnerabilities check runs on pushes to main and on a weekly schedule, and dependency alerts (Renovate + GitHub) surface any new ones for prompt patching.",
   "no_leaked_credentials_status": "Met",
   "no_leaked_credentials_justification": "No credentials are stored in the repository; gitleaks and GitHub secret scanning run in CI, sensitive config is gitignored, and session URLs/tokens are redacted in logs.",
   "static_analysis_status": "Met",

clauster-0.3.0/.coderabbit.yaml

@@ -0,0 +1,54 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# CodeRabbit configuration. Schema: https://www.coderabbit.ai/integrations/schema.v2.json
+#
+# Docstrings: our gate is ruff's pydocstyle (D) rules, enforced on EVERY PR by the
+# "lint" CI job (.github/workflows/lint.yml, `on: pull_request`). It requires
+# docstrings on all public modules/classes/functions (pep257 convention; D105/D107
+# and tests/** are intentionally exempt — see pyproject.toml).
+#
+# CodeRabbit's separate docstring-coverage pre-merge check computes a raw
+# percentage that counts inner/nested helpers (preexec closures, signal handlers,
+# test fixtures) which our gate deliberately exempts, so it reports a misleadingly
+# low number against its 80% default. Defer to ruff D as the single source of
+# truth and turn the redundant check off rather than run two disagreeing gates.
+language: "en-US"
+reviews:
+  profile: "chill"
+  # Don't gate merges on a CodeRabbit "request changes" state — it isn't a
+  # required check and we don't want it blocking the solo merge flow.
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  pre_merge_checks:
+    docstrings:
+      mode: "off"
+  auto_review:
+    enabled: true
+    drafts: false
+    # Skip bot-authored PRs (Renovate, release-please). They only touch deps /
+    # CHANGELOG / version files, and skipping them lets auto-merge proceed without
+    # waiting on review-thread resolution (the `main` ruleset requires it).
+    ignore_usernames:
+      - "renovate[bot]"
+      - "clauster-release-bot[bot]"
+  # Don't spend review effort on vendored / generated / lockfile content.
+  path_filters:
+    - "!src/clauster/static/vendor/**"
+    - "!**/*.min.js"
+    - "!**/*.min.css"
+    - "!uv.lock"
+    - "!package-lock.json"
+  path_instructions:
+    - path: "src/clauster/templates/**"
+      instructions: >-
+        These are Jinja2 templates (autoescape on) driving Alpine.js. Values
+        rendered with {{ }} are HTML-escaped by default — don't flag ordinary
+        interpolation as XSS. Only raw / `| safe` output, or interpolation into
+        event-handler attributes / inline script, is a genuine concern.
+    - path: "tests/**"
+      instructions: >-
+        Tests use FastAPI's TestClient. WebSocket and background-task tests must
+        wrap the client in `with _client(...)` so the app lifespan/startup runs.
+chat:
+  auto_reply: true

clauster-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug report
+description: Something in Clauster isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thanks for taking the time to file a bug. **For security vulnerabilities,
+        do not open an issue** — report it privately via a
+        [GitHub Security Advisory](https://github.com/schubydoo/clauster/security/advisories/new)
+        (see [SECURITY.md](https://github.com/schubydoo/clauster/blob/main/SECURITY.md)).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Clauster version
+      description: Output of `clauster --version`, or the Docker image tag.
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: Install method
+      options:
+        - pip / uv (PyPI)
+        - Docker (GHCR)
+        - from source
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Python version, browser (for a UI bug), reverse proxy (if any).
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste `clauster` output or bridge logs. Redact any tokens or secrets.
+      render: shell

clauster-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability (report privately)
+    url: https://github.com/schubydoo/clauster/security/advisories/new
+    about: Please report security issues privately via a GitHub Security Advisory — do not open a public issue.

clauster-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do that Clauster doesn't support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see happen?
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or workarounds you've tried or thought about.

clauster-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+<!-- markdownlint-disable-file -->
+
+## What
+
+<!-- What does this PR change, and why? Link any related issue. -->
+
+## Checklist
+
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) — it becomes the squashed commit subject that release-please parses (and the required `conventional PR title` check gates it).
+- [ ] Tests added/updated for the change (the `tests` check enforces a 96% coverage gate).
+- [ ] Docs / README updated where user-facing behaviour or config changed.
+- [ ] `uv run pytest` and `uv run pre-commit run -a` pass locally.
+
+<!-- The CHANGELOG is generated from commit history by release-please — no manual CHANGELOG edits are needed. -->

clauster-0.3.0/.github/repo-config/labels.json

@@ -0,0 +1,15 @@
+[
+  { "name": "bug", "color": "d73a4a", "description": "Something isn't working" },
+  { "name": "enhancement", "color": "a2eeef", "description": "New feature or request" },
+  { "name": "documentation", "color": "0075ca", "description": "Improvements or additions to documentation" },
+  { "name": "question", "color": "d876e3", "description": "Further information is requested" },
+  { "name": "good first issue", "color": "7057ff", "description": "Good for newcomers" },
+  { "name": "help wanted", "color": "008672", "description": "Extra attention is needed" },
+  { "name": "breaking", "color": "b60205", "description": "Backwards-incompatible change" },
+  { "name": "security", "color": "d93f0b", "description": "Security-related — Renovate vulnerability alerts use this" },
+  { "name": "dependencies", "color": "ededed", "description": "Renovate-opened dependency update PRs (and the dashboard issue)" },
+  { "name": "vendored-assets", "color": "ededed", "description": "Renovate heads-up to re-vendor self-hosted front-end assets (manual dist update)" },
+  { "name": "autorelease: pending", "color": "ededed", "description": "Release Please — release PR is open, awaiting merge" },
+  { "name": "autorelease: tagged", "color": "0e8a16", "description": "Release Please — release PR is merged and the tag has been pushed" },
+  { "name": "autorelease: snapshot", "color": "5319e7", "description": "Release Please — snapshot/prerelease (rare)" }
+]

clauster-0.3.0/.github/rulesets/README.md

@@ -0,0 +1,63 @@
+# Repository rulesets
+
+`main.json` is the source-of-truth for the **`main` branch ruleset** — the
+replacement for the legacy branch-protection rules previously declared in
+`.github/settings.yml` and reconciled by the [`repository-settings`][app] Probot
+app. That config file is removed in this PR, and the app itself has been
+uninstalled from the repository — the ruleset is now the sole source of branch
+protection.
+
+It encodes the same contract the project has always enforced:
+
+- required status checks (`ci required checks passed`, `security required checks
+  passed`, `conventional PR title`, `lint`) with strict / up-to-date branches,
+- linear history, conversation resolution, a pull request required (0 approvals —
+  solo maintainer), and blocked deletions / force-pushes,
+- `enforcement: active` with an empty `bypass_actors` list — i.e. admins are
+  enforced too (the old `enforce_admins: true`).
+
+## Tag protection + immutable releases
+
+`tags.json` is a second ruleset (`target: tag`) over `refs/tags/v*` that blocks
+**deletion** and **non-fast-forward** (moving) of release tags, with no bypass —
+so a published version tag can't be repointed or removed. Tag *creation* is not
+blocked, so release-please can still cut new `vX.Y.Z` tags.
+
+This pairs with **immutable releases** (enabled on the repo via
+`PUT /repos/{owner}/{repo}/immutable-releases`): once a release is published its
+tag is locked to its commit and its assets can't be changed, and a release
+attestation is generated. Immutability applies to *future* releases only; the
+release **body/notes remain editable**, so the post-publish
+`gh release edit --notes-file` step (when needed) still works.
+
+## Applying
+
+The rulesets are currently applied/maintained manually via the API. Each file
+maps to one ruleset: `main.json` → ruleset **`main`** (branch), `tags.json` →
+ruleset **`protect-version-tags`** (tag).
+
+```sh
+# create (first time)
+gh api -X POST repos/<owner>/<repo>/rulesets --input .github/rulesets/main.json
+gh api -X POST repos/<owner>/<repo>/rulesets --input .github/rulesets/tags.json
+
+# update an existing ruleset (look up its id by name first)
+id=$(gh api repos/<owner>/<repo>/rulesets --jq '.[]|select(.name=="main")|.id')
+gh api -X PUT repos/<owner>/<repo>/rulesets/"$id" --input .github/rulesets/main.json
+id=$(gh api repos/<owner>/<repo>/rulesets --jq '.[]|select(.name=="protect-version-tags")|.id')
+gh api -X PUT repos/<owner>/<repo>/rulesets/"$id" --input .github/rulesets/tags.json
+
+# verify: effective branch rules, every ruleset, and immutable releases
+gh api repos/<owner>/<repo>/rules/branches/main
+gh api repos/<owner>/<repo>/rulesets --jq '.[]|{id,name,target,enforcement}'
+gh api repos/<owner>/<repo>/immutable-releases   # expect {"enabled": true, ...}
+```
+
+Immutable releases is a repo setting, not a ruleset file: enable with
+`gh api -X PUT repos/<owner>/<repo>/immutable-releases` (disable with `-X DELETE`).
+
+A small GitHub Action to reconcile these files (plus repo settings and labels)
+automatically — applying on merge and re-applying on a schedule to revert
+out-of-band drift — is planned. Until then, edit the JSON and re-apply by hand.
+
+[app]: https://github.com/repository-settings/app

clauster-0.3.0/.github/rulesets/main.json

@@ -0,0 +1,53 @@
+{
+  "name": "main",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": ["~DEFAULT_BRANCH"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    { "type": "required_linear_history" },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": ["squash"]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": true,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          { "context": "ci required checks passed", "integration_id": 15368 },
+          { "context": "security required checks passed", "integration_id": 15368 },
+          { "context": "conventional PR title", "integration_id": 15368 },
+          { "context": "lint", "integration_id": 15368 }
+        ]
+      }
+    },
+    {
+      "type": "code_scanning",
+      "parameters": {
+        "code_scanning_tools": [
+          {
+            "tool": "CodeQL",
+            "security_alerts_threshold": "high_or_higher",
+            "alerts_threshold": "errors"
+          }
+        ]
+      }
+    }
+  ]
+}

clauster-0.3.0/.github/rulesets/tags.json

@@ -0,0 +1,16 @@
+{
+  "name": "protect-version-tags",
+  "target": "tag",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/tags/v*"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" }
+  ]
+}

{clauster-0.2.2 → clauster-0.3.0}/.github/workflows/lint.yml

@@ -15,7 +15,8 @@ concurrency:
 jobs:
   lint:
     # This job name is a REQUIRED status check — it must match the context list
-    # in .github/settings.yml exactly (renaming means updating that list too).
+    # in the `main` ruleset (.github/rulesets/main.json) exactly (renaming means
+    # updating that ruleset too).
     # Runs ruff (check + format), pyright, and the Markdown + YAML doc-lint
     # (scripts/lint-docs.sh).
     name: lint

clauster-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

{clauster-0.2.2 → clauster-0.3.0}/.yamllint.yaml

@@ -29,5 +29,5 @@ rules:
     level: warning
   # Workflow/config files routinely omit the `---` start marker.
   document-start: disable
-  # Probot Settings uses comments aligned under keys; don't fight that.
+  # Some config files align comments under keys; don't fight that.
   comments-indentation: disable

{clauster-0.2.2 → clauster-0.3.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.3.0](https://github.com/schubydoo/clauster/compare/v0.2.2...v0.3.0) (2026-06-03)
+
+
+### Features
+
+* **docker:** add a Docker Compose quickstart ([#97](https://github.com/schubydoo/clauster/issues/97)) ([e6c914d](https://github.com/schubydoo/clauster/commit/e6c914d22e648ede2dd3c0285a717fdae5f1bef2))
+* **doctor:** check that the claude CLI is logged in ([#84](https://github.com/schubydoo/clauster/issues/84)) ([f902f23](https://github.com/schubydoo/clauster/commit/f902f23af6876f1cc95e450c0d4f1447c5e71cfe))
+
+
+### Bug Fixes
+
+* **runner:** serialize concurrent spawns of the same project ([#91](https://github.com/schubydoo/clauster/issues/91)) ([2dc8eb0](https://github.com/schubydoo/clauster/commit/2dc8eb044aaed3e735627f2feedbce8281a6b298))
+* **runner:** stop wiping persisted metadata for untracked projects ([#92](https://github.com/schubydoo/clauster/issues/92)) ([cca1c69](https://github.com/schubydoo/clauster/commit/cca1c69ec29a48c2d034d64cdf5a23e4dca1383a))
+* show Restart for stopped pty bridges so true-resume is reachable ([#99](https://github.com/schubydoo/clauster/issues/99)) ([5ea38aa](https://github.com/schubydoo/clauster/commit/5ea38aaa0b2ed92039681be4babe32c7ba9ad465))
+
 ## [0.2.2](https://github.com/schubydoo/clauster/compare/v0.2.1...v0.2.2) (2026-06-03)
 
 

{clauster-0.2.2 → clauster-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clauster
-Version: 0.2.2
+Version: 0.3.0
 Summary: Self-hosted web UI for spawning and managing Claude Code remote-control bridges on a remote host.
 Project-URL: Homepage, https://github.com/schubydoo/clauster
 Project-URL: Repository, https://github.com/schubydoo/clauster
@@ -59,7 +59,8 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
+  <a href="https://pypi.org/project/clauster/"><img alt="PyPI" src="https://img.shields.io/pypi/v/clauster?logo=pypi&logoColor=white"></a>
+  <a href="https://pypi.org/project/clauster/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/clauster"></a>
   <a href="https://github.com/schubydoo/clauster/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
   <a href="https://github.com/schubydoo/clauster/pkgs/container/clauster"><img alt="GHCR" src="https://img.shields.io/badge/ghcr.io-clauster-2496ED?logo=docker&logoColor=white"></a>
   <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
@@ -121,7 +122,7 @@ it in [`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/c
   permission mode per launch. `bypassPermissions` is double-gated: a per-project
   config ceiling (`projects.<name>.allow_bypass_permissions`) **and** a
   type-the-project-name confirm in the UI.
-- **Open in Claude** — a deep link to the primary session plus a scannable QR code
+- **Open session in Claude** — a deep link to the primary session plus a scannable QR code
   that opens it in the Claude app (claude.ai/code or mobile), attached to the
   running bridge.
 - **External session surfacing** — sessions you started from a terminal or Desktop
@@ -183,6 +184,33 @@ uv run clauster
 Then open <http://127.0.0.1:7621>. `claude` must be on your `PATH` (Clauster spawns
 it; it isn't vendored).
 
+## First bridge in 60 seconds
+
+With the server running (above) and `claude` on your `PATH`, spawning your first
+bridge is a handful of clicks — no terminal needed once it's started:
+
+1. **Point Clauster at your code.** Set `projects_root` in `clauster.yml` to a
+   directory whose subfolders are projects (e.g. `~/code`); each child directory
+   becomes a card.
+2. **Sanity-check the host (optional).** `clauster doctor` confirms `claude` is found
+   and new enough and that `projects_root` / the state dir are usable — fix any ✗
+   before spawning.
+3. **Open the dashboard** at <http://127.0.0.1:7621>. You'll see one card per project.
+4. **Start a bridge.** On a project's card, click **Start**. Clauster launches
+   `claude remote-control` in that directory and the card flips to *Running* with a
+   live status badge. (Pick a spawn / permission mode first if you like — the
+   defaults are safe.)
+5. **Attach from anywhere.** Use the card's **Open session in Claude** link — or scan its
+   **QR code** — to pick the bridge up in `claude.ai/code` or the Claude mobile app.
+   No SSH session.
+6. **Stop or restart.** **Stop** signals the bridge; **Restart** relaunches it (with
+   `claude.resume_recap` or `resume_mode: pty` it can carry the prior conversation
+   forward — see [Opt-in extras](#opt-in-extras)).
+
+> Exposing this beyond loopback (e.g. on your LAN)? Read
+> [Auth & networking](#auth--networking) first — a non-loopback bind requires
+> authentication.
+
 ## Docker
 
 Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release.
@@ -223,6 +251,19 @@ docker run -d --name clauster \
 - Logs are JSON by default (`CLAUSTER_LOG_FORMAT`); health is at `/healthz`. Images
   are cosign-signed with build provenance + SBOM attestations.
 
+### Docker Compose
+
+A ready-to-edit [`compose.yaml`](https://github.com/schubydoo/clauster/blob/main/compose.yaml) is included:
+
+```sh
+# 1. generate a password hash (runs inside the image)
+docker compose run --rm clauster clauster hash-password
+# 2. export it single-quoted, then edit the projects/claude volumes in compose.yaml
+export CLAUSTER_AUTH_PASSWORD_HASH='$argon2id$v=19$...'
+# 3. start (the image's HEALTHCHECK is inherited)
+docker compose up -d
+```
+
 ## Auth & networking
 
 Loopback (`127.0.0.1`) needs no auth. Binding to a non-loopback address is refused

{clauster-0.2.2 → clauster-0.3.0}/README.md

@@ -16,7 +16,8 @@
 </p>
 
 <p align="center">
-  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
+  <a href="https://pypi.org/project/clauster/"><img alt="PyPI" src="https://img.shields.io/pypi/v/clauster?logo=pypi&logoColor=white"></a>
+  <a href="https://pypi.org/project/clauster/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/clauster"></a>
   <a href="https://github.com/schubydoo/clauster/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
   <a href="https://github.com/schubydoo/clauster/pkgs/container/clauster"><img alt="GHCR" src="https://img.shields.io/badge/ghcr.io-clauster-2496ED?logo=docker&logoColor=white"></a>
   <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
@@ -78,7 +79,7 @@ it in [`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/c
   permission mode per launch. `bypassPermissions` is double-gated: a per-project
   config ceiling (`projects.<name>.allow_bypass_permissions`) **and** a
   type-the-project-name confirm in the UI.
-- **Open in Claude** — a deep link to the primary session plus a scannable QR code
+- **Open session in Claude** — a deep link to the primary session plus a scannable QR code
   that opens it in the Claude app (claude.ai/code or mobile), attached to the
   running bridge.
 - **External session surfacing** — sessions you started from a terminal or Desktop
@@ -140,6 +141,33 @@ uv run clauster
 Then open <http://127.0.0.1:7621>. `claude` must be on your `PATH` (Clauster spawns
 it; it isn't vendored).
 
+## First bridge in 60 seconds
+
+With the server running (above) and `claude` on your `PATH`, spawning your first
+bridge is a handful of clicks — no terminal needed once it's started:
+
+1. **Point Clauster at your code.** Set `projects_root` in `clauster.yml` to a
+   directory whose subfolders are projects (e.g. `~/code`); each child directory
+   becomes a card.
+2. **Sanity-check the host (optional).** `clauster doctor` confirms `claude` is found
+   and new enough and that `projects_root` / the state dir are usable — fix any ✗
+   before spawning.
+3. **Open the dashboard** at <http://127.0.0.1:7621>. You'll see one card per project.
+4. **Start a bridge.** On a project's card, click **Start**. Clauster launches
+   `claude remote-control` in that directory and the card flips to *Running* with a
+   live status badge. (Pick a spawn / permission mode first if you like — the
+   defaults are safe.)
+5. **Attach from anywhere.** Use the card's **Open session in Claude** link — or scan its
+   **QR code** — to pick the bridge up in `claude.ai/code` or the Claude mobile app.
+   No SSH session.
+6. **Stop or restart.** **Stop** signals the bridge; **Restart** relaunches it (with
+   `claude.resume_recap` or `resume_mode: pty` it can carry the prior conversation
+   forward — see [Opt-in extras](#opt-in-extras)).
+
+> Exposing this beyond loopback (e.g. on your LAN)? Read
+> [Auth & networking](#auth--networking) first — a non-loopback bind requires
+> authentication.
+
 ## Docker
 
 Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release.
@@ -180,6 +208,19 @@ docker run -d --name clauster \
 - Logs are JSON by default (`CLAUSTER_LOG_FORMAT`); health is at `/healthz`. Images
   are cosign-signed with build provenance + SBOM attestations.
 
+### Docker Compose
+
+A ready-to-edit [`compose.yaml`](https://github.com/schubydoo/clauster/blob/main/compose.yaml) is included:
+
+```sh
+# 1. generate a password hash (runs inside the image)
+docker compose run --rm clauster clauster hash-password
+# 2. export it single-quoted, then edit the projects/claude volumes in compose.yaml
+export CLAUSTER_AUTH_PASSWORD_HASH='$argon2id$v=19$...'
+# 3. start (the image's HEALTHCHECK is inherited)
+docker compose up -d
+```
+
 ## Auth & networking
 
 Loopback (`127.0.0.1`) needs no auth. Binding to a non-loopback address is refused

clauster-0.3.0/compose.yaml

@@ -0,0 +1,38 @@
+# Clauster — Docker Compose quickstart. See the README "Docker" section for the full rundown.
+#
+# Clauster binds 0.0.0.0 inside the container, so it REQUIRES enforced auth to start.
+#
+#   1. Generate a password hash (runs inside the image — nothing needed on the host):
+#        docker compose run --rm clauster clauster hash-password
+#   2. Provide the printed `$argon2id$…` hash. Easiest + safest is to export it
+#      single-quoted (single quotes stop your shell expanding the `$`):
+#        export CLAUSTER_AUTH_PASSWORD_HASH='$argon2id$v=19$...'
+#      (Or put it in a .env file beside this one — but then double every `$` to `$$`
+#       so Compose doesn't try to interpolate it.)
+#   3. Point the `projects` volume at your projects_root, and mount the `claude` CLI +
+#      credentials (Clauster spawns `claude remote-control`; the CLI is NOT in the image).
+#   4. docker compose up -d
+
+services:
+  clauster:
+    image: ghcr.io/schubydoo/clauster:latest
+    container_name: clauster
+    restart: unless-stopped
+    ports:
+      - "7621:7621"
+    environment:
+      # Non-loopback bind => enforced auth is mandatory (the container exits otherwise).
+      CLAUSTER_AUTH_ENABLED: "true"
+      CLAUSTER_AUTH_PASSWORD_REQUIRED: "true"
+      CLAUSTER_AUTH_PASSWORD_HASH: ${CLAUSTER_AUTH_PASSWORD_HASH:?run clauster hash-password and export it (see header)}
+      # Remap the runtime user to own the bind-mounts (match your host UID/GID).
+      PUID: "1000"
+      PGID: "1000"
+    volumes:
+      - ./config:/config            # clauster.yml + state_dir
+      - ./projects:/projects        # the projects_root to manage (point at your repos)
+      # `claude` is NOT baked into the image. Mount it onto PATH + mount the runtime
+      # user's ~/.claude credentials (or build a derived image that installs claude):
+      # - /usr/local/bin/claude:/usr/local/bin/claude:ro
+      # - ~/.claude:/config/.claude
+    # The image already defines a HEALTHCHECK against /healthz — Compose inherits it.

{clauster-0.2.2 → clauster-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clauster"
-version = "0.2.2"
+version = "0.3.0"
 description = "Self-hosted web UI for spawning and managing Claude Code remote-control bridges on a remote host."
 readme = "README.md"
 requires-python = ">=3.11"

{clauster-0.2.2 → clauster-0.3.0}/renovate.json

@@ -9,12 +9,16 @@
   "timezone": "Etc/UTC",
   "schedule": ["before 7am on monday"],
   "labels": ["dependencies"],
+  "description": "Auto-merge uses GitHub native auto-merge + squash (a real PR satisfying the main ruleset), NOT branch automerge — the ruleset requires a PR, so branch automerge would be blocked.",
+  "platformAutomerge": true,
+  "automergeStrategy": "squash",
   "vulnerabilityAlerts": {
     "enabled": true,
     "labels": ["security"]
   },
   "lockFileMaintenance": {
     "enabled": true,
+    "automerge": true,
     "schedule": ["before 7am on monday"]
   },
   "ignorePaths": [
@@ -47,11 +51,10 @@
       "labels": ["vendored-assets"]
     },
     {
-      "description": "Auto-merge patch updates of dev tooling.",
+      "description": "Auto-merge patch + minor updates of dev/test tooling once CI passes (a failing check blocks the merge).",
       "matchPackageNames": ["ruff", "pyright", "pytest", "pytest-cov", "pytest-asyncio"],
-      "matchUpdateTypes": ["patch"],
-      "automerge": true,
-      "automergeType": "branch"
+      "matchUpdateTypes": ["patch", "minor"],
+      "automerge": true
     },
     {
       "description": "Group all pytest-related updates.",
@@ -64,11 +67,18 @@
       "groupName": "ruff"
     },
     {
-      "description": "Roll all non-major GitHub Actions updates into one weekly PR.",
+      "description": "Roll non-major GitHub Actions version updates into one weekly PR (reviewed).",
       "matchManagers": ["github-actions"],
-      "matchUpdateTypes": ["minor", "patch", "digest"],
+      "matchUpdateTypes": ["minor", "patch"],
       "groupName": "github-actions (non-major)"
     },
+    {
+      "description": "Auto-merge GitHub Actions digest re-pins (same version, new SHA) once CI passes.",
+      "matchManagers": ["github-actions"],
+      "matchUpdateTypes": ["digest"],
+      "groupName": "github-actions digests",
+      "automerge": true
+    },
     {
       "description": "Group security-tooling actions — same security.yml scanners, useful to review together.",
       "matchManagers": ["github-actions"],

{clauster-0.2.2 → clauster-0.3.0}/src/clauster/__init__.py

@@ -1,3 +1,3 @@
 """Clauster — self-hosted dispatcher for Claude Code remote-control bridges."""
 
-__version__ = "0.2.2"  # x-release-please-version
+__version__ = "0.3.0"  # x-release-please-version

{clauster-0.2.2 → clauster-0.3.0}/src/clauster/config.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import ipaddress
 import os
 from pathlib import Path
-from typing import Annotated, Literal
+from typing import Literal
 
 import yaml
 from pydantic import BaseModel, Field, PrivateAttr, field_validator, model_validator
@@ -255,9 +255,6 @@ class ClausterConfig(BaseModel):
         return self
 
 
-ConfigPath = Annotated[Path, "resolved path the config was loaded from, or None"]
-
-
 def _candidate_paths(explicit: Path | None) -> list[Path]:
     if explicit is not None:
         return [explicit]