Skip to content

feat: add opt-in Linux host-root access - #24

Merged
oll4com merged 10 commits into
mainfrom
feature/linux-host-root-access
Jul 27, 2026
Merged

oll4com merged 10 commits into
mainfrom
feature/linux-host-root-access

Conversation

@oll4com

@oll4com oll4com commented Jul 27, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add explicit Linux-only --access isolated|host-root installation mode
  • mount host / at /host read-only in core and read/write in the CLI service
  • run CLI sessions as container root only for the exact host-root opt-in
  • add Arch-family/CachyOS Docker prerequisite bootstrap
  • prepare 0.1.15-hostroot.0 for the npm personal tag without changing latest

Security boundaries

  • new and migrated installations remain isolated by default
  • macOS and Windows reject explicit or persisted host-root state before Docker preparation
  • no Docker socket, privileged mode, host PID/network/IPC namespaces, or devices
  • failed access activation restores the previous runtime or stops a failed clean install
  • switching back to --access isolated removes /host while preserving persistent state

Verification

  • npm run test:public
  • npm run check
  • npm run build
  • npm audit --audit-level=high (0 vulnerabilities)
  • npm run pack:dry-run -w run-spaceapp
  • npm run hygiene:status
  • npm run hygiene:preflight
  • node scripts/public-release-readiness.mjs --version 0.1.15-hostroot.0
  • real Docker Compose merge validation for light/standard × isolated/host-root
  • npm/GHCR immutable artifact preflight
  • npm tarball inspection: 12 allowlisted files, no generated config, secrets, or host overlay

The repository-wide npm test still stops at the pre-existing @space/contracts
workspace because it declares vitest run but contains no test files. The
canonical CI and release command is npm run test:public, which passes.

Rollout

After required CI and review are green, merge to main, then dispatch the OIDC
release with version 0.1.15-hostroot.0 and npm tag personal. Keep latest
and next unchanged. Real CachyOS acceptance remains required before handing
the install command to the owner.

Rollback

Before publish: close this PR and delete the feature branch. After publish:
restore npm dist-tags if any protected tag changed, keep immutable exact-version
artifacts for audit, and switch the test installation back to isolated mode.

Summary by CodeRabbit

  • New Features

    • Added an opt-in Linux host-root access mode for personal prerelease installations.
    • Added --access isolated|host-root, with isolated access remaining the default.
    • Added support for publishing releases with either the next or personal npm tag.
    • Added Arch-family Docker installation support through pacman.
  • Bug Fixes

    • Install failures now roll back changes and restore the previous runtime where possible.
  • Documentation

    • Added setup, operations, security, architecture, and acceptance guidance for host-root access.

@coderabbitai

coderabbitai Bot commented Jul 27, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@oll4com, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 40 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b364ce46-cd76-4385-905f-42b6fb614ee3

📥 Commits

Reviewing files that changed from the base of the PR and between 0782298 and e530d72.

📒 Files selected for processing (21)
  • .github/workflows/release.yml
  • README.md
  • deploy/docker/cli-entrypoint.sh
  • docs/clean-room-testing.md
  • docs/operations.md
  • docs/public-release.md
  • packages/run-spaceapp/README.md
  • packages/run-spaceapp/src/cli.mjs
  • packages/run-spaceapp/tests/cli.test.mjs
  • scripts/public-export.mjs
  • scripts/public-release-readiness.mjs
  • scripts/release-artifact-preflight.mjs
  • scripts/release-version.mjs
  • scripts/tests/public-docker-distribution.test.mjs
  • scripts/tests/public-export.test.mjs
  • scripts/tests/public-package-metadata.test.mjs
  • scripts/tests/public-release-readiness.test.mjs
  • scripts/tests/public-suite.test.mjs
  • scripts/tests/public-workflows.test.mjs
  • scripts/tests/release-version.test.mjs
  • scripts/verify-published-containers.mjs
📝 Walkthrough

Walkthrough

The PR adds an opt-in Linux host-root installation mode, persists access settings through configuration and Compose, supports Arch-family Docker setup, adds rollback handling, and publishes the prerelease through a selectable personal npm tag.

Changes

Host-root installation and runtime

Layer / File(s) Summary
Access configuration and Compose wiring
packages/run-spaceapp/src/index.mjs, packages/run-spaceapp/src/package-info.mjs, deploy/docker/cli-entrypoint.sh
Adds schema version 3 with accessMode, generates host-access Compose overlays, and runs the CLI as root only when the explicit environment flag is true.
Installer transitions and prerequisites
packages/run-spaceapp/src/cli.mjs, packages/run-spaceapp/src/prerequisites.mjs
Adds --access isolated|host-root, Linux validation, rollback after runtime mutations, Arch/CachyOS pacman Docker installation, and access-mode propagation through resume flows.
Runtime and public contract validation
packages/run-spaceapp/tests/*, scripts/tests/*
Tests configuration migration, Compose mounts, rollback behavior, command contracts, entrypoint gating, and personal-channel metadata.

Release and documentation

Layer / File(s) Summary
Prerelease release channel
.github/workflows/release.yml, packages/run-spaceapp/package.json, scripts/*
Adds selectable next/personal npm tags and permits semantic prerelease versions including 0.1.15-hostroot.0.
Host-root documentation and acceptance
README.md, docs/*, packages/run-spaceapp/README.md
Documents host-root installation, /host mount permissions, security boundaries, operational commands, release procedures, and CachyOS acceptance testing.

Estimated code review effort: 5 (Critical) | ~90 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant Launcher
  participant Compose
  participant Core
  participant CLI
  Operator->>Launcher: install --access host-root
  Launcher->>Compose: write and load host-access overlay
  Compose->>Core: mount /host read-only
  Compose->>CLI: mount /host read-write
  CLI->>CLI: run as container root when enabled
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: an opt-in Linux host-root access mode.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Replace the private acceptance target identifier with a generic live-installation boundary so the sanitized export remains publishable.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 8

🧹 Nitpick comments (3)
packages/run-spaceapp/src/cli.mjs (1)

609-623: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicated usage string.

The same usage message is constructed twice; extract it once.

♻️ Suggested refactor
 function parseInstallArgs(args) {
+  const usage = `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--access isolated|host-root] [--no-open]`;
   let requestedProfile = "auto";

and replace both throw new Error(...) bodies with throw new Error(usage);.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/run-spaceapp/src/cli.mjs` around lines 609 - 623, Extract the
repeated install usage text into a shared `usage` variable near the validation
logic, then replace both `throw new Error(...)` constructions in the `install`
argument checks with `throw new Error(usage)`.
packages/run-spaceapp/tests/cli.test.mjs (1)

647-647: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Version literals are duplicated across assertions.

These now hardcode 0.1.15-hostroot.0 in several places and must be edited on every release. Importing PACKAGE_VERSION from src/package-info.mjs would keep them in sync.

Also applies to: 680-681, 715-718

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/run-spaceapp/tests/cli.test.mjs` at line 647, Update the assertions
in the CLI tests, including the referenced ranges, to import and reuse
PACKAGE_VERSION from src/package-info.mjs instead of hardcoding
0.1.15-hostroot.0; preserve the existing regular-expression matching behavior
while deriving every version expectation from that shared value.
packages/run-spaceapp/src/prerequisites.mjs (1)

646-672: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Only the Arch branch uses idFamily.

Debian/Ubuntu and Fedora/RHEL derivatives still match on ID alone, so e.g. Linux Mint or Rocky fall through to the unsupported message even though ID_LIKE identifies them. Consider using idFamily consistently for all three branches (keeping id for codename/repo selection).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/run-spaceapp/src/prerequisites.mjs` around lines 646 - 672, Update
the distribution checks in the Docker engine installation flow to use idFamily
for Debian/Ubuntu and Fedora/RHEL branches, so ID_LIKE derivatives such as Mint
and Rocky are recognized. Keep using the original id when passing the Debian
codename and selecting repository-specific behavior, and leave the existing Arch
branch unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/release.yml:
- Around line 10-17: Update the release workflow’s npm_tag handling to enforce
the invariant that versions containing the host-root marker map exclusively to
the personal tag, preventing them from publishing to next; either derive the tag
from inputs.version or add a pre-publish validation guard, and extend the
workflow test to cover this mapping.
- Around line 360-361: Update the “Publish sanitized tarball to selected
prerelease channel” step so the workflow expression for inputs.npm_tag is
assigned through the step’s env configuration, then reference that environment
variable as "$RELEASE_DIST_TAG" in the npm publish command. Keep the existing
artifact path, provenance flag, and publish behavior unchanged.

In `@deploy/docker/cli-entrypoint.sh`:
- Around line 23-25: Update the host-root handling in cli-entrypoint.sh so
root-created state under /var/lib/spaceapp-cli cannot block later isolated
sessions. Before launching the isolated-mode path, recursively restore ownership
of that state directory to spaceapp, or otherwise ensure host-root sessions use
a separate state directory; preserve the existing root-mode execution through
packages/cli-host/dist/main.js.

In `@docs/clean-room-testing.md`:
- Around line 101-104: Add an explicit effective-user verification to the
container-root execution procedure, using a command such as id -u and requiring
UID 0 before accepting host-root behavior. Keep the existing mount permission,
file mutation, and isolation checks unchanged.

In `@packages/run-spaceapp/README.md`:
- Around line 71-72: Keep all prerelease follow-up commands on the same launcher
channel: update the provider, token, credentials, and uninstall examples in
packages/run-spaceapp/README.md (lines 71-72), the token-rotation example in
README.md (lines 118-119), and the rollback example in docs/operations.md (lines
122-124) to use `@personal`, or explicitly document any intentional `@latest`
exception.
- Around line 61-64: Update the security description in the README paragraph to
distinguish the CLI service’s read/write host-root mount from the core service’s
read-only /host mount. Preserve the existing warnings and clarify that
spaceapp-core receives the host mount read-only.

In `@packages/run-spaceapp/src/cli.mjs`:
- Around line 507-513: Update the failed-install recovery flow around
restoreRuntimeAfterFailedInstall so the previous runtime is re-committed to the
persistent root before recovery completes, and restart it using paths under root
rather than stagedStateRoot. Ensure failAfterRuntimeMutation and subsequent
Compose operations no longer retain references to the temporary directory that
the finally block removes.

In `@scripts/public-release-readiness.mjs`:
- Line 8: Replace the versionPattern validators in
scripts/public-release-readiness.mjs (line 8),
scripts/release-artifact-preflight.mjs (line 7), and
scripts/verify-published-containers.mjs (line 7) with a complete SemVer
validator that rejects leading zeros in numeric core and prerelease identifiers
while accepting valid build metadata such as 1.0.0+build.123; keep all release
gates consistent with the package version contract.

---

Nitpick comments:
In `@packages/run-spaceapp/src/cli.mjs`:
- Around line 609-623: Extract the repeated install usage text into a shared
`usage` variable near the validation logic, then replace both `throw new
Error(...)` constructions in the `install` argument checks with `throw new
Error(usage)`.

In `@packages/run-spaceapp/src/prerequisites.mjs`:
- Around line 646-672: Update the distribution checks in the Docker engine
installation flow to use idFamily for Debian/Ubuntu and Fedora/RHEL branches, so
ID_LIKE derivatives such as Mint and Rocky are recognized. Keep using the
original id when passing the Debian codename and selecting repository-specific
behavior, and leave the existing Arch branch unchanged.

In `@packages/run-spaceapp/tests/cli.test.mjs`:
- Line 647: Update the assertions in the CLI tests, including the referenced
ranges, to import and reuse PACKAGE_VERSION from src/package-info.mjs instead of
hardcoding 0.1.15-hostroot.0; preserve the existing regular-expression matching
behavior while deriving every version expectation from that shared value.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 48ce503f-8214-44d0-8cc2-6305c53db33c

📥 Commits

Reviewing files that changed from the base of the PR and between f6956f3 and 0782298.

⛔ Files ignored due to path filters (1)
  • package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (29)
  • .github/workflows/release.yml
  • README.md
  • deploy/docker/cli-entrypoint.sh
  • docs/clean-room-testing.md
  • docs/decisions/ADR-011-linux-host-root-access.md
  • docs/getting-started.md
  • docs/operations.md
  • docs/public-release.md
  • docs/security-model.md
  • docs/specs/linux-host-root-access.md
  • packages/run-spaceapp/README.md
  • packages/run-spaceapp/package.json
  • packages/run-spaceapp/src/cli.mjs
  • packages/run-spaceapp/src/index.mjs
  • packages/run-spaceapp/src/package-info.mjs
  • packages/run-spaceapp/src/prerequisites.mjs
  • packages/run-spaceapp/tests/cli.test.mjs
  • packages/run-spaceapp/tests/command-contracts.test.mjs
  • packages/run-spaceapp/tests/config.test.mjs
  • packages/run-spaceapp/tests/prerequisites.test.mjs
  • packages/run-spaceapp/tests/runtime.test.mjs
  • scripts/public-release-readiness.mjs
  • scripts/release-artifact-preflight.mjs
  • scripts/tests/public-compose-config.test.mjs
  • scripts/tests/public-docker-distribution.test.mjs
  • scripts/tests/public-package-metadata.test.mjs
  • scripts/tests/public-release-readiness.test.mjs
  • scripts/tests/public-workflows.test.mjs
  • scripts/verify-published-containers.mjs

Comment on lines +10 to +17
npm_tag:
description: npm prerelease channel
required: true
default: next
type: choice
options:
- next
- personal

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Enforce the host-root version-to-tag invariant.

packages/run-spaceapp/src/package-info.mjs maps -hostroot. versions to personal, while this input defaults to next and permits next for the same version. A normal dispatch can therefore publish 0.1.15-hostroot.0 to next while the documented @personal command remains stale. Add a pre-publish guard or derive the tag from inputs.version; update the workflow test with that invariant.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/release.yml around lines 10 - 17, Update the release
workflow’s npm_tag handling to enforce the invariant that versions containing
the host-root marker map exclusively to the personal tag, preventing them from
publishing to next; either derive the tag from inputs.version or add a
pre-publish validation guard, and extend the workflow test to cover this
mapping.

Comment thread .github/workflows/release.yml Resolved
Comment thread deploy/docker/cli-entrypoint.sh Resolved
Comment thread docs/clean-room-testing.md Resolved
Comment thread packages/run-spaceapp/README.md Resolved
Comment thread packages/run-spaceapp/README.md Resolved
Comment thread packages/run-spaceapp/src/cli.mjs Resolved
Comment thread scripts/public-release-readiness.mjs Resolved
@oll4com
oll4com merged commit 5a8c1b9 into main Jul 27, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant