Support reliable self-update for server-side and headless core instances (tinyhumansai#1458)

Author: senamakel

.env.example

@@ -74,6 +74,11 @@ OPENHUMAN_WORKSPACE=
 OPENHUMAN_TEMPERATURE=0.7
 # [optional] Skill + agent tool execution timeout in seconds (default 120, max 3600)
 # OPENHUMAN_TOOL_TIMEOUT_SECS=
+# [optional] Headless update restart contract: self_replace | supervisor
+# OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=self_replace
+# [optional] Allow bearer-authenticated RPC callers to invoke update.apply/update.run
+# Disable on exposed server deployments unless you explicitly want remote self-upgrade.
+# OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=true
 
 # ---------------------------------------------------------------------------
 # Runtime flags

app/src-tauri/Cargo.lock

@@ -43,6 +43,7 @@ Applies to every release, all platforms.
 
 - [ ] **`.deb` and/or `.AppImage` install on a clean Ubuntu 22.04** — `sudo dpkg -i openhuman_*.deb` or `chmod +x openhuman-*.AppImage && ./openhuman-*.AppImage`. Expected: no missing-dependency errors; app launches.
 - [ ] **OS-native notification toasts fire** — Trigger a notification from inside the app (e.g. memory captured, agent finished). Expected: a libnotify-style toast appears outside the app window. (CI Linux sees only Xvfb; this surface verifies on a real desktop.)
+- [ ] **Headless supervisor update stages without self-exit** — On a Linux service deployment with `[update] restart_strategy = "supervisor"` and `rpc_mutations_enabled = false`, stage a new core binary through the documented operator flow. Expected: the running process stays up until the supervisor restart, the staged binary is present on disk, and `systemctl restart openhuman` (or equivalent) picks up the new version.
 
 ### Cross-platform
 

docs/RELEASE-MANUAL-SMOKE.md

@@ -48,7 +48,7 @@ Canonical mapping of every product feature to its test source(s). Drives gap-fil
 
 | ID    | Feature                       | Layer | Test path(s)                                       | Status | Notes                                 |
 | ----- | ----------------------------- | ----- | -------------------------------------------------- | ------ | ------------------------------------- |
-| 0.3.1 | Auto Update Check             | RU+MS | `src/openhuman/update/` (Rust unit), release smoke | 🟡     | Core check covered; UI prompt manual  |
+| 0.3.1 | Auto Update Check             | RU+RI+MS | `src/openhuman/update/` (Rust unit), `tests/json_rpc_e2e.rs`, release smoke | 🟡     | Core check/update policy covered; desktop prompt + release upgrade still manual |
 | 0.3.2 | Forced Update Handling        | MS    | release-manual-smoke                               | 🚫     | End-to-end gating verified at release |
 | 0.3.3 | Reinstall with Existing State | MS    | release-manual-smoke                               | 🚫     | Workspace persistence on reinstall    |
 | 0.3.4 | Clean Uninstall               | MS    | release-manual-smoke                               | 🚫     | OS removal paths                      |

docs/TEST-COVERAGE-MATRIX.md

@@ -214,6 +214,54 @@ Then run `openhuman-core serve` under your service manager of choice
 (systemd, supervisord, …) with the same environment variables documented
 above.
 
+### Headless self-update contract
+
+Headless deployments should treat `openhuman.update_apply` as the safe primitive:
+it downloads the release asset, writes it atomically next to the current binary,
+and returns. Nothing exits automatically.
+
+`openhuman.update_run` follows `config.update.restart_strategy`:
+
+- `self_replace` (default): stage the binary, publish an in-process restart request, and let the running core respawn itself.
+- `supervisor`: stage the binary and return `restart_requested=false`. Your outer service manager must restart the process.
+
+For long-running Linux services, set:
+
+```toml
+[update]
+restart_strategy = "supervisor"
+rpc_mutations_enabled = false
+```
+
+or the equivalent env vars:
+
+```bash
+OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=supervisor
+OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=false
+```
+
+Recommended `systemd` stance:
+
+```ini
+Restart=always
+ExecReload=/bin/kill -HUP $MAINPID
+```
+
+Operator flow:
+
+1. Call `openhuman.update_check` to discover a release.
+2. Configure `restart_strategy = "supervisor"` in your `update.toml` (or set
+   `OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=supervisor`) so the core stages the
+   new binary without trying to re-exec itself, then call
+   `openhuman.update_apply` or `openhuman.update_run`. `restart_strategy` is a
+   configuration setting, not an RPC parameter.
+3. Restart the unit explicitly: `systemctl restart openhuman`.
+
+If download or staging fails, the running binary is left in place and no
+restart is requested. If a staged binary proves bad after restart, roll back by
+restoring the previous binary from your package manager, image tag, or release
+artifact and restarting the supervisor again.
+
 The Compose file ([`docker-compose.yml`](../../docker-compose.yml)) maps the core
 on `:7788`, mounts a named volume `openhuman-workspace` for persistence, and
 sets `restart: unless-stopped` so the core comes back after host reboots.
@@ -226,6 +274,10 @@ docker compose build
 docker compose up -d
 ```
 
+For RPC-exposed production deployments, prefer leaving mutating update RPCs
+disabled (`OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=false`) and perform
+rollouts through your existing image tag or package-management flow instead.
+
 ### Logs
 
 ```bash

gitbooks/features/cloud-deploy.md

@@ -922,7 +922,7 @@ const CAPABILITIES: &[Capability] = &[
         name: "Apply Core Update",
         domain: "update",
         category: CapabilityCategory::Settings,
-        description: "Download and stage a newer core binary, then restart the sidecar.",
+        description: "Download and stage a newer core binary. Desktop builds can self-restart; headless deployments can hand restart off to a supervisor.",
         how_to: "Settings > Developer Options > Apply Update",
         status: CapabilityStatus::Beta,
         privacy: None,

src/openhuman/about_app/catalog.rs

@@ -34,9 +34,9 @@ pub use schema::{
     ReliabilityConfig, ResourceLimitsConfig, RuntimeConfig, SandboxBackend, SandboxConfig,
     SchedulerConfig, SchedulerGateConfig, SchedulerGateMode, ScreenIntelligenceConfig,
     SecretsConfig, SecurityConfig, SlackConfig, StorageConfig, StorageProviderConfig,
-    StorageProviderSection, StreamMode, TelegramConfig, UpdateConfig, VoiceActivationMode,
-    VoiceServerConfig, WebSearchConfig, WebhookConfig, DEFAULT_CLOUD_LLM_MODEL, DEFAULT_MODEL,
-    MODEL_AGENTIC_V1, MODEL_CODING_V1, MODEL_REASONING_V1,
+    StorageProviderSection, StreamMode, TelegramConfig, UpdateConfig, UpdateRestartStrategy,
+    VoiceActivationMode, VoiceServerConfig, WebSearchConfig, WebhookConfig,
+    DEFAULT_CLOUD_LLM_MODEL, DEFAULT_MODEL, MODEL_AGENTIC_V1, MODEL_CODING_V1, MODEL_REASONING_V1,
 };
 pub use schema::{
     clear_active_user, default_root_openhuman_dir, pre_login_user_dir, read_active_user_id,

src/openhuman/config/mod.rs

@@ -5,7 +5,7 @@ use super::{
         normalize_no_proxy_list, normalize_proxy_url_option, normalize_service_list,
         parse_proxy_enabled, parse_proxy_scope, set_runtime_proxy_config, ProxyScope,
     },
-    Config,
+    Config, UpdateRestartStrategy,
 };
 use anyhow::{Context, Result};
 use directories::UserDirs;
@@ -1061,6 +1061,30 @@ impl Config {
                 self.update.interval_minutes = minutes;
             }
         }
+        if let Some(raw) = env.get("OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY") {
+            match raw.trim().to_ascii_lowercase().as_str() {
+                "self_replace" | "self-replace" | "self" => {
+                    self.update.restart_strategy = UpdateRestartStrategy::SelfReplace;
+                }
+                "supervisor" | "stage_only" | "stage-only" => {
+                    self.update.restart_strategy = UpdateRestartStrategy::Supervisor;
+                }
+                other => {
+                    tracing::warn!(
+                        value = other,
+                        "ignoring invalid OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY \
+                         (valid: self_replace, supervisor)"
+                    );
+                }
+            }
+        }
+        if let Some(flag) = env.get("OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED") {
+            if let Some(enabled) =
+                parse_env_bool("OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED", &flag)
+            {
+                self.update.rpc_mutations_enabled = enabled;
+            }
+        }
 
         // Dictation overrides
         if let Some(flag) = env.get("OPENHUMAN_DICTATION_ENABLED") {

src/openhuman/config/schema/load.rs

@@ -810,6 +810,35 @@ fn env_overlay_auto_update_interval_parses_u32() {
     assert_eq!(cfg.update.interval_minutes, 60);
 }
 
+#[test]
+fn env_overlay_auto_update_restart_strategy_accepts_supported_values() {
+    let mut cfg = Config::default();
+    cfg.apply_env_overlay_with(
+        &HashMapEnv::new().with("OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY", "supervisor"),
+    );
+    assert_eq!(
+        cfg.update.restart_strategy,
+        crate::openhuman::config::UpdateRestartStrategy::Supervisor
+    );
+
+    cfg.apply_env_overlay_with(
+        &HashMapEnv::new().with("OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY", "self_replace"),
+    );
+    assert_eq!(
+        cfg.update.restart_strategy,
+        crate::openhuman::config::UpdateRestartStrategy::SelfReplace
+    );
+}
+
+#[test]
+fn env_overlay_auto_update_rpc_mutations_enabled_parses_bool() {
+    let mut cfg = Config::default();
+    cfg.apply_env_overlay_with(
+        &HashMapEnv::new().with("OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED", "false"),
+    );
+    assert!(!cfg.update.rpc_mutations_enabled);
+}
+
 #[test]
 fn env_overlay_empty_lookup_leaves_defaults_intact() {
     // The seam with no env entries should be a no-op on a fresh Config.

src/openhuman/config/schema/load_tests.rs

@@ -66,7 +66,7 @@ pub use tools::{
     GitbooksConfig, HttpRequestConfig, IntegrationToggle, IntegrationsConfig, MultimodalConfig,
     SecretsConfig, WebSearchConfig,
 };
-pub use update::UpdateConfig;
+pub use update::{UpdateConfig, UpdateRestartStrategy};
 mod voice_server;
 pub use voice_server::{VoiceActivationMode, VoiceServerConfig};
 mod types;