Skip to content

feat(service): prefer systemd user units - #10813

Closed
hugoncosta wants to merge 2 commits into
kirodotdev:mainfrom
hugoncosta:feat/systemd-user-service-default
Closed

hugoncosta wants to merge 2 commits into
kirodotdev:mainfrom
hugoncosta:feat/systemd-user-service-default

Conversation

@hugoncosta

Copy link
Copy Markdown

Problem / Motivation

On Linux, kirocrew service install used a machine-wide systemd unit even when the current user had a working systemd user manager. This unnecessarily requires sudo for a per-user application and might be a turn-off for some sysadmins that do not want certain users to have sudo.

Why it matters

A user unit provides a least-privilege default and lets users install and control KiroCrew without root access. Hosts without a usable user manager still need the existing system-level fallback.

What changed (motivation → approach → change)

Fresh Linux installations now:

  • Prefer ~/.config/systemd/user/kirocrew.service when systemctl --user is available.
  • Fall back to /etc/systemd/system/kirocrew.service otherwise.
  • Preserve the scope of an existing installation when reinstalling.
  • Use systemctl --user and journalctl --user for user-unit lifecycle and logs.
  • Render user units without system-only directives such as User=, Group=, and the /etc/kirocrew environment file.
  • Keep the existing sudo-backed system installation unchanged as the fallback.

Documentation and CLI guidance were updated accordingly. This does not introduce migration machinery, configuration options, or unrelated service-management changes.

RFC: N/A — no matching non-draft RFC currently exists on main for this default change.

Tests

Added or updated coverage for:

  • Selecting user scope for fresh installations.
  • Falling back when the user manager is unavailable.
  • Retaining the scope of existing installations.
  • User-unit rendering and lifecycle commands.
  • User-scoped journal access.
  • SELinux behavior for user and system installations.

Verification performed:

  • 34 lifecycle tests passed.
  • 43 SELinux service tests passed.
  • Python compilation checks passed.
  • Documentation lint passed.
  • git diff --check passed.
  • CLI help smoke test passed.

Manual verification

CLI output was smoke-tested and a live systemd integration was performed on a machine without sudo.

Related Issues

N/A — no issue linked.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@hugoncosta
hugoncosta requested review from a team and buluoray September 14, 2026 16:10
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 14, 2026
@NicholasRBowers NicholasRBowers added needs-pr-triage PR scanner: awaiting automated triage drive-to-green PR claimed by drive-to-green pipeline and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 21, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author.

Assessment: Both reds are mechanical and come from this PR's own diff, not from the design. The Brand Name Gate fails on one added line in docs/system-specs/modules/security.md that writes the product name as one word ("no KiroCrew or LLM-influenced code runs under sudo") where the gate requires "Kiro Crew"; that red is inside Fast Gate, which is why Await Fast Gate and Coverage Gate are red behind it rather than for reasons of their own. The macOS Backend Tests red is a single assertion in test/test_windows_gap_list.py: windows-expected-failures.txt still names test/test_service.py::TestLinuxUnitRendering::test_install_writes_unit_via_sudo_install_and_invokes_systemctl, a test this PR renamed away, so the gap-list entry now names nothing. Fix plan: rebase onto current main (the branch is 756 commits behind but reports no conflicts), correct the one brand spelling, drop the stale gap-list entry, squash, and re-run the gates.

If you'd prefer I don't touch this PR, add the pr-no-autofix label.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 22, 2026

@bolichen97 bolichen97 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.

Requesting changes: fresh Linux installs are now session-bound and no longer survive logout or reboot

The brand-gate and gap-list reds are already covered in the earlier comment. This review is only about the new default.

Where

  • src/kiro_crew/service/linux.py:669: when no unit exists yet, the code sets user_scope = _user_manager_available(). That probe (linux.py:418-426) returns False only under SUDO_USER or euid 0. Otherwise it returns whether systemctl --user show-environment exits 0, and that passes in any ordinary SSH or desktop login.
  • linux.py:683 then writes render_unit(user_scope=True). That unit has WantedBy=default.target (linux.py:308) and no EnvironmentFile= (linux.py:257).
  • Neither linux.install() nor controller.install_service() (controller.py:120-131) reads Linger=, turns it on, or warns about it.

Failure scenario
An operator SSHes into a VPS and runs kirocrew service install, as remote-and-mobile.md describes. The install succeeds and prints the user unit path. Linger is off by default, so when the last session closes, logind stops user@UID.service and the gateway goes down with it. The dashboard, Slack and cron all stop. Restart=always can't help, because the user manager itself has exited. After a reboot the gateway stays down until that user logs in again.

What this changes
Main promises "survives SSH disconnects, restarts on crash, and starts on boot" (docs/system-specs/modules/cli.md:1355-1356 on main) and "Boot survival via WantedBy=multi-user.target (no linger needed" (cli.md:1413). Main's own user-unit remedy listed loginctl enable-linger <account> as a required step (service/linux.py:580 on main).

The PR mentions linger only in the docs (docs/guides/install.md:659, cli.md:1304). The CLI never mentions it. The only remaining way to get the system unit is implicit: run under sudo, which install.md now says not to do. Existing system-unit installs keep their scope, so the change affects fresh installs and uninstall-then-reinstall.

Smallest fix direction

  • After a user-scope install, check loginctl show-user <user> -p Linger. If it is no, print a clear warning with the exact sudo loginctl enable-linger <user> command, or offer to run it.
  • Add an explicit, documented way to choose the system unit for always-on hosts, for example a --system flag.
  • State the default change as breaking in the PR description so the release notes carry it. After the rebase, main's README.md:223 ("boot-persistent service", added after your merge base) also needs the same update.

From a full open-PR audit against origin/main c66f95b (2026-09-25); findings were checked by independent reviewers reading the code. Reply here if this is wrong.

Copy link
Copy Markdown
Contributor

Triage: needs a rebase. main now covers part of this PR (PARTIALLY_COVERED)

I read the full diff (f739452e..b5e2f848) against current origin/main (a97659dfc3). This PR is 2799 commits behind main. git merge-tree shows conflicts in 8 files: README.md, docs/guides/install.md, docs/system-specs/modules/cli.md, docs/system-specs/modules/security.md, src/kiro_crew/cli_server.py, service/common.py, service/controller.py and service/linux.py.

Already on main (merged PRs)

Not on main, so this part is still open

  • The change of default: a fresh install picks systemctl --user when the user manager answers (linux.py install(): user_scope = _user_manager_available()). Main's module docstring still says a per-user INSTALL mode is "deliberately NOT implemented". So main does not fully cover this PR, and it should not be closed.

Still open from the earlier review

  • Breaking change and linger: @bolichen97's CHANGES_REQUESTED review (2026-09-25) still applies, and I'm not filing a second one. When rebasing, _linger_enabled() from fix(service): warn at system install when the service account has linger off #15851 is the obvious way to warn after a user-scope install, and an explicit system-scope choice is still needed for always-on hosts.
  • Smaller point: at head, stop() / restart() / is_active() call _installed_systemctl, which goes to systemctl --user whenever the file exists, with no sudo or root guard. Main's _user_scope_unreachable_reason() already handles that case.

Recommendation: REBASE onto main using #13964's scope-aware verbs, then CONTINUE-DEVELOPMENT on the default change and the linger handling.

@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you @hugoncosta for pushing on least-privilege installs. We are closing this PR: much of it has since landed in #13964 (scope-aware status, stop, restart and uninstall for user units) and #15851 (linger checks). The remaining part, making a user unit the default, would make fresh installs stop at logout and not start at boot unless linger is on, which breaks the documented always-on behaviour. If you would like to continue, an explicit opt-in (for example a --user flag that checks or enables linger) against current main would be a welcome fresh PR.

The branch is left untouched, so you can reopen this PR at any time, or open a fresh one on current main, if you want to pick it back up.

@iamwhatever iamwhatever closed this Nov 1, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 1, 2026
@mbriones98 mbriones98 removed the drive-to-green PR claimed by drive-to-green pipeline label Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants