mirror of
https://github.com/razzant/ouroboros.git
synced 2026-10-16 13:40:52 +00:00
109 lines
4 KiB
Markdown
109 lines
4 KiB
Markdown
# Running native Linux packages under systemd
|
|
|
|
The native `.deb` and `.rpm` packages ship an optional systemd user unit with a
|
|
stable name. It is an alternative way to launch Ouroboros when an operator wants
|
|
to use `systemctl --user`; the ordinary desktop entry still starts Ouroboros
|
|
directly and is not controlled by this unit.
|
|
|
|
Choose one launch path for an instance. If Ouroboros is already running from the
|
|
desktop entry, close it before starting the unit; the single-instance lock is
|
|
shared by both paths.
|
|
|
|
## Scope
|
|
|
|
The packaged unit is supported only for the native `.deb` and `.rpm` layout. It
|
|
starts the release-reviewed launcher at `/opt/ouroboros/Ouroboros`, the same
|
|
entry point as the packaged desktop file. Source checkouts, AppImages, and
|
|
tarballs have different locations and are deliberately outside this unit's
|
|
contract.
|
|
|
|
The package installs the unit at:
|
|
|
|
```text
|
|
/usr/lib/systemd/user/ouroboros.service
|
|
```
|
|
|
|
Installation never enables or starts it. Starting a desktop agent remains an
|
|
explicit user decision.
|
|
|
|
## Use
|
|
|
|
Start or stop the packaged runtime explicitly:
|
|
|
|
```bash
|
|
systemctl --user start ouroboros
|
|
systemctl --user stop ouroboros
|
|
systemctl --user restart ouroboros
|
|
systemctl --user status ouroboros
|
|
```
|
|
|
|
After Panic, automatic startup and manual `systemctl --user start` or `restart`
|
|
leave Ouroboros stopped; the journal reports "Ouroboros is stopped. Use Start to resume."
|
|
Resume explicitly through the desktop entry or `ouroboros run --start ...`.
|
|
|
|
To start it automatically with the user session:
|
|
|
|
```bash
|
|
systemctl --user enable --now ouroboros
|
|
```
|
|
|
|
Undo that choice with:
|
|
|
|
```bash
|
|
systemctl --user disable --now ouroboros
|
|
```
|
|
|
|
`loginctl enable-linger "$USER"` is an additional, system-level owner choice
|
|
when the user service must survive logout. Without linger, the user manager and
|
|
its services end with the last session.
|
|
|
|
## Readiness
|
|
|
|
`systemctl --user is-active ouroboros` proves only that the launcher process is
|
|
running. `/api/state` reporting `supervisor_ready: true` is necessary before
|
|
task admission, but it is not sufficient: the worker pool has a separate
|
|
admission state and may still return a typed HTTP 503.
|
|
|
|
A successful task admission is the authoritative proof that work was accepted.
|
|
Automation may use a bounded retry policy for the specific typed 503 condition
|
|
it supports; it must not treat process activity or HTTP reachability alone as
|
|
proof that a task entered the queue. `ouroboros status` remains useful for
|
|
checking the loaded branch, SHA, and worker projection.
|
|
|
|
## Logs
|
|
|
|
The journal shows user-service lifecycle and launcher output:
|
|
|
|
```bash
|
|
journalctl --user -u ouroboros -f
|
|
```
|
|
|
|
Ouroboros also keeps its normal application logs under
|
|
`~/Ouroboros/data/logs/`, including `launcher.log` and `agent_stdout.log`.
|
|
|
|
## Lifecycle ownership
|
|
|
|
The unit intentionally has no systemd restart policy. The launcher already owns
|
|
managed restart, its bounded crash fuse, panic semantics, and final cleanup.
|
|
Adding a second restart owner would let systemd undo a panic stop or restart a
|
|
runtime that the launcher deliberately stopped.
|
|
|
|
`KillMode=control-group` sends the stop signal to the complete process tree
|
|
started by the unit, including the launcher, server, and workers.
|
|
`TimeoutStopSec=120` does not defer that signal and does not promise that an
|
|
in-flight tool call will finish. It is the upper bound systemd waits before
|
|
escalating to `SIGKILL` while remaining cgroup processes follow their own
|
|
shutdown paths.
|
|
|
|
This also stops a shared Claudexor daemon if it was spawned inside this unit's
|
|
cgroup, even if it started a separate process session; other clients using that
|
|
daemon lose it too. A daemon already running outside the unit is unaffected.
|
|
Use the ordinary desktop launch path when the daemon must survive an Ouroboros
|
|
service stop.
|
|
|
|
## Why this is a user unit
|
|
|
|
Ouroboros state lives in the invoking user's `~/Ouroboros` directory and the
|
|
desktop launcher uses that user's session. A system unit would run under a
|
|
different identity or require a second state/permission contract, so the native
|
|
packages ship only this opt-in user service.
|