Background service

StructureCopy Anchor Link

User-level service manager (LaunchAgent / systemd --user)
  └─ Supervisor (with endurance observation)
       └─ Daemon: project coordinators, foreground sessions
            └─ Rna SDK: model requests, tool batches, MCP guardians

Start and stopCopy Anchor Link

./rna service start
./rna service status
./rna service stop
./rna service uninstall

service start installs and starts a service for the current user, with no admin rights. Closing the terminal or chat window does not stop work. Stopping records a durable intent, cancels background work and closes within a limit; the restart policy will not bring it back. Uninstalling removes only the service definition and keeps projects, sessions, memory configuration and evidence.

If the service should also host a local dependency (for example a Docker-compatible OpenViking relay), use ./rna service restart --helper-descriptor PATH (repeatable), and --without-helpers to clear them explicitly. It is not needed with the built-in local memory.

The macOS “Documents” folder permissionCopy Anchor Link

If the workspace is under Documents and Node has not been granted background access, the native service may hang before starting. Choose session mode explicitly:

./rna service start --session
./rna service restart --native   # switch back once permission is granted

In session mode the daemon is still independent of windows and is recovered by the supervisor; but if the supervisor itself exits, you log out or restart, it is not restored. The installer never changes privacy settings.

Keys and the background environmentCopy Anchor Link

The credentials file saved from Settings is usable by the background service directly. If a provider only references a shell environment variable, make sure the service environment has it too; the installer never copies shell keys into the plist.

Endurance observationCopy Anchor Link

./rna endurance start               # picks a window from actual history
./rna endurance start --hours 120 --keep-awake
./rna endurance status
./rna endurance stop

It checks the service every 5 seconds, keeps a summary every minute, and records failures and instance changes immediately. Restarts, sleep gaps and clock jumps never count as continuous health.

--keep-awake runs caffeinate -i -s only during this observation, preventing idle sleep and system sleep on AC power; the display may still sleep, and global power settings are untouched. Closing the lid, manual sleep, power loss, logout or network loss still break continuity.