{"record":{"id":"71608aca61df94c9","repo":"zeroclaw-labs/zeroclaw","slug":"linux-service-action-only-manages-the-default-ze","errorCode":null,"errorMessage":"Linux service {action} only manages the default zeroclaw service. Config directory {config_dir} maps to named service {service}; provide that unit manually, then use service status/start/stop/restart/logs to manage it.","messagePattern":"Linux service (.+?) only manages the default zeroclaw service\\. Config directory (.+?) maps to named service (.+?); provide that unit manually, then use service status/start/stop/restart/logs to manage it\\.","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-runtime/src/service/mod.rs","lineNumber":639,"sourceCode":"    format!(\"{}.service\", linux_service_base(config))\n}\n\nfn linux_openrc_service(config: &Config) -> String {\n    linux_service_base(config)\n}\n\nfn ensure_linux_default_install_scope(config: &Config, action: &str) -> Result<()> {\n    let service = linux_service_base(config);\n    if service == \"zeroclaw\" {\n        return Ok(());\n    }\n\n    let config_dir = config\n        .config_path\n        .parent()\n        .map(|path| path.display().to_string())\n        .unwrap_or_else(|| config.config_path.display().to_string());\n    bail!(\n        \"Linux service {action} only manages the default zeroclaw service. \\\n         Config directory {config_dir} maps to named service {service}; \\\n         provide that unit manually, then use service status/start/stop/restart/logs to manage it.\"\n    );\n}\n\nfn linux_systemd_action_args(config: &Config, action: &str) -> Vec<String> {\n    vec![\n        \"--user\".to_string(),\n        action.to_string(),\n        linux_systemd_unit(config),\n    ]\n}\n\nfn linux_openrc_action_args(config: &Config, action: &str) -> Vec<String> {\n    vec![linux_openrc_service(config), action.to_string()]\n}\n","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-runtime/src/service/mod.rs#L621-L657","documentation":"On Linux, install/uninstall only manage the default zeroclaw systemd unit. ensure_linux_default_install_scope derives the service name from the config directory; a non-default directory maps to a named service which the installer refuses to create, so it bails and tells you to provide that unit manually.","triggerScenarios":"Running 'zeroclaw service install' or 'zeroclaw service uninstall' on Linux while the config path (e.g. via ZEROCLAW_CONFIG_DIR or --config) lives in a non-default directory such as ~/.config/zeroclaw-second that maps to a named zeroclaw@<name> service.","commonSituations":"Running multiple zeroclaw instances from separate config dirs; automation that reuses one custom config path across hosts; CI pipelines setting a config dir before installing.","solutions":["Run install/uninstall with the default config directory (~/.config/zeroclaw) for the service-managed instance","Or drop the named unit in yourself (zeroclaw@<name>.service template under ~/.config/systemd/user/) and manage it via 'zeroclaw service status/start/stop/restart/logs' with that config dir","Reserve per-instance config dirs for manually provisioned units only"],"exampleFix":"# before\nZEROCLAW_CONFIG_DIR=~/.config/zeroclaw-second zeroclaw service install\n\n# after: provide the named unit manually, then manage it\ncp zeroclaw@.service ~/.config/systemd/user/\nZEROCLAW_CONFIG_DIR=~/.config/zeroclaw-second zeroclaw service start","handlingStrategy":"validation","validationCode":"fn manages_default_scope_only(config: &Config) -> bool {\n    let dir = config.config_path.parent().map(|p| p.to_path_buf());\n    let home = std::env::var(\"HOME\").unwrap_or_default();\n    dir == Some(std::path::Path::new(&home).join(\".config\").join(\"zeroclaw\"))\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Invoke service install/uninstall only with the default config directory","Template the named systemd unit yourself for extra instances","Document which config dirs are service-managed versus manually managed"],"tags":["linux","systemd","service","named-instance","config-directory"],"backgroundTag":"unsupported-configuration","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}