feat: Nix mode config, UX, onboarding, SwiftPM plist, docs

apps/macos/Package.swift

@@ -49,6 +49,9 @@ let package = Package(
                 .product(name: "PeekabooBridge", package: "PeekabooCore"),
                 .product(name: "PeekabooAutomationKit", package: "PeekabooAutomationKit"),
             ],
+            exclude: [
+                "Resources/Info.plist",
+            ],
             resources: [
                 .copy("Resources/Clawdis.icns"),
                 .copy("Resources/DeviceModels"),

apps/macos/Sources/Clawdis/ClawdisConfigFile.swift

@@ -20,6 +20,7 @@ enum ClawdisConfigFile {
     }
 
     static func saveDict(_ dict: [String: Any]) {
+        if ProcessInfo.processInfo.isNixMode { return }
         do {
             let data = try JSONSerialization.data(withJSONObject: dict, options: [.prettyPrinted, .sortedKeys])
             let url = self.url()

apps/macos/Sources/Clawdis/ConfigSettings.swift

@@ -3,6 +3,7 @@ import SwiftUI
 @MainActor
 struct ConfigSettings: View {
     private let isPreview = ProcessInfo.processInfo.isPreview
+    private let isNixMode = ProcessInfo.processInfo.isNixMode
     private let state = AppStateStore.shared
     private let labelColumnWidth: CGFloat = 120
     private static let browserAttachOnlyHelp =
@@ -52,8 +53,11 @@ struct ConfigSettings: View {
         VStack(alignment: .leading, spacing: 14) {
             self.header
             self.agentSection
+                .disabled(self.isNixMode)
             self.heartbeatSection
+                .disabled(self.isNixMode)
             self.browserSection
+                .disabled(self.isNixMode)
             Spacer(minLength: 0)
         }
         .frame(maxWidth: .infinity, alignment: .leading)
@@ -66,7 +70,9 @@ struct ConfigSettings: View {
     private var header: some View {
         Text("Clawdis CLI config")
             .font(.title3.weight(.semibold))
-        Text("Edit ~/.clawdis/clawdis.json (agent / session / routing / messages).")
+        Text(self.isNixMode
+            ? "This tab is read-only in Nix mode. Edit config via Nix and rebuild."
+            : "Edit ~/.clawdis/clawdis.json (agent / session / routing / messages).")
             .font(.callout)
             .foregroundStyle(.secondary)
     }
@@ -300,7 +306,7 @@ struct ConfigSettings: View {
     }
 
     private func autosaveConfig() {
-        guard self.allowAutosave else { return }
+        guard self.allowAutosave, !self.isNixMode else { return }
         Task { await self.saveConfig() }
     }
 

apps/macos/Sources/Clawdis/GeneralSettings.swift

@@ -17,6 +17,7 @@ struct GeneralSettings: View {
     @State private var remoteStatus: RemoteStatus = .idle
     @State private var showRemoteAdvanced = false
     private let isPreview = ProcessInfo.processInfo.isPreview
+    private var isNixMode: Bool { ProcessInfo.processInfo.isNixMode }
 
     var body: some View {
         ScrollView(.vertical) {
@@ -125,7 +126,10 @@ struct GeneralSettings: View {
             }
 
             if self.state.connectionMode == .local {
-                self.gatewayInstallerCard
+                // In Nix mode, gateway is managed declaratively - no install buttons.
+                if !self.isNixMode {
+                    self.gatewayInstallerCard
+                }
                 TailscaleIntegrationSection(
                     connectionMode: self.state.connectionMode,
                     isPaused: self.state.isPaused)

apps/macos/Sources/Clawdis/Onboarding.swift

@@ -15,6 +15,13 @@ final class OnboardingController {
     private var window: NSWindow?
 
     func show() {
+        if ProcessInfo.processInfo.isNixMode {
+            // Nix mode is fully declarative; onboarding would suggest interactive setup that doesn't apply.
+            UserDefaults.standard.set(true, forKey: "clawdis.onboardingSeen")
+            UserDefaults.standard.set(currentOnboardingVersion, forKey: onboardingVersionKey)
+            AppStateStore.shared.onboardingSeen = true
+            return
+        }
         if let window {
             DockIconManager.shared.temporarilyShowDock()
             window.makeKeyAndOrderFront(nil)

apps/macos/Sources/Clawdis/PermissionsSettings.swift

@@ -45,6 +45,24 @@ struct PermissionStatusList: View {
             .font(.footnote)
             .padding(.top, 2)
             .help("Refresh status")
+
+            if (self.status[.accessibility] ?? false) == false || (self.status[.screenRecording] ?? false) == false {
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("Note: macOS may require restarting Clawdis after enabling Accessibility or Screen Recording.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+
+                    Button {
+                        LaunchdManager.startClawdis()
+                    } label: {
+                        Label("Restart Clawdis", systemImage: "arrow.counterclockwise")
+                    }
+                    .buttonStyle(.bordered)
+                    .controlSize(.small)
+                }
+                .padding(.top, 4)
+            }
         }
     }
 

apps/macos/Sources/Clawdis/ProcessInfo+Clawdis.swift

@@ -5,6 +5,11 @@ extension ProcessInfo {
         self.environment["XCODE_RUNNING_FOR_PREVIEWS"] == "1"
     }
 
+    var isNixMode: Bool {
+        if self.environment["CLAWDIS_NIX_MODE"] == "1" { return true }
+        return UserDefaults.standard.bool(forKey: "clawdis.nixMode")
+    }
+
     var isRunningTests: Bool {
         // SwiftPM tests load one or more `.xctest` bundles. With Swift Testing, `Bundle.main` is not
         // guaranteed to be the `.xctest` bundle, so check all loaded bundles.

apps/macos/Sources/Clawdis/Resources/Info.plist

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleDevelopmentRegion</key>
+    <string>en</string>
+    <key>CFBundleExecutable</key>
+    <string>Clawdis</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.steipete.clawdis</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>Clawdis</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.0.0</string>
+    <key>CFBundleVersion</key>
+    <string>0.0.0</string>
+    <key>CFBundleIconFile</key>
+    <string>Clawdis</string>
+    <key>CFBundleURLTypes</key>
+    <array>
+        <dict>
+            <key>CFBundleURLName</key>
+            <string>com.steipete.clawdis.deeplink</string>
+            <key>CFBundleURLSchemes</key>
+            <array>
+                <string>clawdis</string>
+            </array>
+        </dict>
+    </array>
+    <key>LSMinimumSystemVersion</key>
+    <string>15.0</string>
+    <key>LSUIElement</key>
+    <true/>
+
+    <key>ClawdisBuildTimestamp</key>
+    <string></string>
+    <key>ClawdisGitCommit</key>
+    <string></string>
+
+    <key>NSUserNotificationUsageDescription</key>
+    <string>Clawdis needs notification permission to show alerts for agent actions.</string>
+    <key>NSScreenCaptureDescription</key>
+    <string>Clawdis captures the screen when the agent needs screenshots for context.</string>
+    <key>NSCameraUsageDescription</key>
+    <string>Clawdis can capture photos or short video clips when requested by the agent.</string>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Clawdis needs the mic for Voice Wake tests and agent audio capture.</string>
+    <key>NSSpeechRecognitionUsageDescription</key>
+    <string>Clawdis uses speech recognition to detect your Voice Wake trigger phrase.</string>
+    <key>NSAppleEventsUsageDescription</key>
+    <string>Clawdis needs Automation (AppleScript) permission to drive Terminal and other apps for agent actions.</string>
+
+    <key>NSAppTransportSecurity</key>
+    <dict>
+        <key>NSAllowsArbitraryLoadsInWebContent</key>
+        <true/>
+        <key>NSExceptionDomains</key>
+        <dict>
+            <key>100.100.100.100</key>
+            <dict>
+                <key>NSExceptionAllowsInsecureHTTPLoads</key>
+                <true/>
+                <key>NSIncludesSubdomains</key>
+                <true/>
+            </dict>
+        </dict>
+    </dict>
+</dict>
+</plist>

apps/macos/Sources/Clawdis/SettingsRootView.swift

@@ -8,6 +8,7 @@ struct SettingsRootView: View {
     @State private var selectedTab: SettingsTab = .general
     let updater: UpdaterProviding?
     private let isPreview = ProcessInfo.processInfo.isPreview
+    private let isNixMode = ProcessInfo.processInfo.isNixMode
 
     init(state: AppState, updater: UpdaterProviding?, initialTab: SettingsTab? = nil) {
         self.state = state
@@ -16,55 +17,61 @@ struct SettingsRootView: View {
     }
 
     var body: some View {
-        TabView(selection: self.$selectedTab) {
+        VStack(alignment: .leading, spacing: 12) {
-            GeneralSettings(state: self.state)
+            if self.isNixMode {
-                .tabItem { Label("General", systemImage: "gearshape") }
+                self.nixManagedBanner
-                .tag(SettingsTab.general)
-
-            ConnectionsSettings()
-                .tabItem { Label("Connections", systemImage: "link") }
-                .tag(SettingsTab.connections)
-
-            VoiceWakeSettings(state: self.state)
-                .tabItem { Label("Voice Wake", systemImage: "waveform.circle") }
-                .tag(SettingsTab.voiceWake)
-
-            ConfigSettings()
-                .tabItem { Label("Config", systemImage: "slider.horizontal.3") }
-                .tag(SettingsTab.config)
-
-            InstancesSettings()
-                .tabItem { Label("Instances", systemImage: "network") }
-                .tag(SettingsTab.instances)
-
-            SessionsSettings()
-                .tabItem { Label("Sessions", systemImage: "clock.arrow.circlepath") }
-                .tag(SettingsTab.sessions)
-
-            CronSettings()
-                .tabItem { Label("Cron", systemImage: "calendar") }
-                .tag(SettingsTab.cron)
-
-            SkillsSettings(state: self.state)
-                .tabItem { Label("Skills", systemImage: "sparkles") }
-                .tag(SettingsTab.skills)
-
-            PermissionsSettings(
-                status: self.permissionMonitor.status,
-                refresh: self.refreshPerms,
-                showOnboarding: { OnboardingController.shared.show() })
-                .tabItem { Label("Permissions", systemImage: "lock.shield") }
-                .tag(SettingsTab.permissions)
-
-            if self.state.debugPaneEnabled {
-                DebugSettings()
-                    .tabItem { Label("Debug", systemImage: "ant") }
-                    .tag(SettingsTab.debug)
             }
 
-            AboutSettings(updater: self.updater)
+            TabView(selection: self.$selectedTab) {
-                .tabItem { Label("About", systemImage: "info.circle") }
+                GeneralSettings(state: self.state)
-                .tag(SettingsTab.about)
+                    .tabItem { Label("General", systemImage: "gearshape") }
+                    .tag(SettingsTab.general)
+
+                ConnectionsSettings()
+                    .tabItem { Label("Connections", systemImage: "link") }
+                    .tag(SettingsTab.connections)
+
+                VoiceWakeSettings(state: self.state)
+                    .tabItem { Label("Voice Wake", systemImage: "waveform.circle") }
+                    .tag(SettingsTab.voiceWake)
+
+                ConfigSettings()
+                    .tabItem { Label("Config", systemImage: "slider.horizontal.3") }
+                    .tag(SettingsTab.config)
+
+                InstancesSettings()
+                    .tabItem { Label("Instances", systemImage: "network") }
+                    .tag(SettingsTab.instances)
+
+                SessionsSettings()
+                    .tabItem { Label("Sessions", systemImage: "clock.arrow.circlepath") }
+                    .tag(SettingsTab.sessions)
+
+                CronSettings()
+                    .tabItem { Label("Cron", systemImage: "calendar") }
+                    .tag(SettingsTab.cron)
+
+                SkillsSettings(state: self.state)
+                    .tabItem { Label("Skills", systemImage: "sparkles") }
+                    .tag(SettingsTab.skills)
+
+                PermissionsSettings(
+                    status: self.permissionMonitor.status,
+                    refresh: self.refreshPerms,
+                    showOnboarding: { OnboardingController.shared.show() })
+                    .tabItem { Label("Permissions", systemImage: "lock.shield") }
+                    .tag(SettingsTab.permissions)
+
+                if self.state.debugPaneEnabled {
+                    DebugSettings()
+                        .tabItem { Label("Debug", systemImage: "ant") }
+                        .tag(SettingsTab.debug)
+                }
+
+                AboutSettings(updater: self.updater)
+                    .tabItem { Label("About", systemImage: "info.circle") }
+                    .tag(SettingsTab.about)
+            }
         }
         .padding(.horizontal, 28)
         .padding(.vertical, 22)
@@ -98,6 +105,35 @@ struct SettingsRootView: View {
         }
     }
 
+    private var nixManagedBanner: some View {
+        let configPath = ProcessInfo.processInfo.environment["CLAWDIS_CONFIG_PATH"] ?? "~/.clawdis/clawdis.json"
+        let stateDir = ProcessInfo.processInfo.environment["CLAWDIS_STATE_DIR"] ?? "~/.clawdis"
+
+        return VStack(alignment: .leading, spacing: 6) {
+            HStack(spacing: 8) {
+                Image(systemName: "gearshape.2.fill")
+                    .foregroundStyle(.secondary)
+                Text("Managed by Nix")
+                    .font(.callout.weight(.semibold))
+                    .foregroundStyle(.secondary)
+            }
+
+            VStack(alignment: .leading, spacing: 2) {
+                Text("Config: \(configPath)")
+                Text("State:  \(stateDir)")
+            }
+            .font(.caption.monospaced())
+            .foregroundStyle(.secondary)
+            .textSelection(.enabled)
+            .lineLimit(1)
+            .truncationMode(.middle)
+        }
+        .padding(.vertical, 8)
+        .padding(.horizontal, 10)
+        .background(Color.gray.opacity(0.12))
+        .cornerRadius(10)
+    }
+
     private func validTab(for requested: SettingsTab) -> SettingsTab {
         if requested == .debug, !self.state.debugPaneEnabled { return .general }
         return requested

docs/index.md

@@ -116,6 +116,7 @@ Example:
 
 - Start here:
   - [Configuration](./configuration.md)
+  - [Nix mode](./nix.md)
   - [Clawd personal assistant setup](./clawd.md)
   - [Skills](./skills.md)
   - [Workspace templates](./templates/AGENTS.md)

docs/nix.md

@@ -0,0 +1,49 @@
+---
+summary: "Running Clawdis under Nix (config, state, and packaging expectations)"
+read_when:
+  - Building Clawdis with Nix
+  - Debugging Nix-mode behavior
+---
+# Nix mode
+
+Clawdis supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
+Enable it by exporting:
+
+```
+CLAWDIS_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell env vars. You can
+also enable Nix mode via defaults:
+
+```
+defaults write com.steipete.clawdis clawdis.nixMode -bool true
+```
+
+## Config + state paths
+
+Clawdis reads JSON5 config from `CLAWDIS_CONFIG_PATH` and stores mutable data in `CLAWDIS_STATE_DIR`.
+
+- `CLAWDIS_STATE_DIR` (default: `~/.clawdis`)
+- `CLAWDIS_CONFIG_PATH` (default: `$CLAWDIS_STATE_DIR/clawdis.json`)
+
+When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
+stay out of the immutable store.
+
+## Runtime behavior in Nix mode
+
+- Auto-install and self-mutation flows should be disabled.
+- Missing dependencies should surface Nix-specific remediation messages.
+- UI surfaces a read-only Nix mode banner when present.
+
+## Packaging note (macOS)
+
+The macOS packaging flow expects a stable Info.plist template at:
+
+```
+apps/macos/Sources/Clawdis/Resources/Info.plist
+```
+
+`scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields
+(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
+packaging and Nix builds (which do not rely on a full Xcode toolchain).

scripts/package-mac-app.sh

@@ -47,81 +47,27 @@ mkdir -p "$APP_ROOT/Contents/Resources"
 mkdir -p "$APP_ROOT/Contents/Resources/Relay"
 mkdir -p "$APP_ROOT/Contents/Frameworks"
 
-echo "📄 Writing Info.plist"
+echo "📄 Copying Info.plist template"
-cat > "$APP_ROOT/Contents/Info.plist" <<PLIST
+INFO_PLIST_SRC="$ROOT_DIR/apps/macos/Sources/Clawdis/Resources/Info.plist"
-<?xml version="1.0" encoding="UTF-8"?>
+if [ ! -f "$INFO_PLIST_SRC" ]; then
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+  echo "ERROR: Info.plist template missing at $INFO_PLIST_SRC" >&2
-<plist version="1.0">
+  exit 1
-<dict>
+fi
-    <key>CFBundleIdentifier</key>
+cp "$INFO_PLIST_SRC" "$APP_ROOT/Contents/Info.plist"
-    <string>${BUNDLE_ID}</string>
+/usr/libexec/PlistBuddy -c "Set :CFBundleIdentifier ${BUNDLE_ID}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>CFBundleShortVersionString</key>
+/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString ${APP_VERSION}" "$APP_ROOT/Contents/Info.plist" || true
-    <string>${APP_VERSION}</string>
+/usr/libexec/PlistBuddy -c "Set :CFBundleVersion ${APP_BUILD}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>CFBundleVersion</key>
+/usr/libexec/PlistBuddy -c "Set :ClawdisBuildTimestamp ${BUILD_TS}" "$APP_ROOT/Contents/Info.plist" || true
-    <string>${APP_BUILD}</string>
+/usr/libexec/PlistBuddy -c "Set :ClawdisGitCommit ${GIT_COMMIT}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>CFBundleName</key>
+/usr/libexec/PlistBuddy -c "Set :SUFeedURL ${SPARKLE_FEED_URL}" "$APP_ROOT/Contents/Info.plist" \
-    <string>Clawdis</string>
+  || /usr/libexec/PlistBuddy -c "Add :SUFeedURL string ${SPARKLE_FEED_URL}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>CFBundleExecutable</key>
+/usr/libexec/PlistBuddy -c "Set :SUPublicEDKey ${SPARKLE_PUBLIC_ED_KEY}" "$APP_ROOT/Contents/Info.plist" \
-    <string>Clawdis</string>
+  || /usr/libexec/PlistBuddy -c "Add :SUPublicEDKey string ${SPARKLE_PUBLIC_ED_KEY}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>CFBundleIconFile</key>
+if /usr/libexec/PlistBuddy -c "Set :SUEnableAutomaticChecks ${AUTO_CHECKS}" "$APP_ROOT/Contents/Info.plist"; then
-    <string>Clawdis</string>
+  true
-    <key>CFBundlePackageType</key>
+else
-    <string>APPL</string>
+  /usr/libexec/PlistBuddy -c "Add :SUEnableAutomaticChecks bool ${AUTO_CHECKS}" "$APP_ROOT/Contents/Info.plist" || true
-    <key>LSMinimumSystemVersion</key>
+fi
-    <string>15.0</string>
-    <key>LSUIElement</key>
-    <true/>
-    <key>CFBundleURLTypes</key>
-    <array>
-        <dict>
-            <key>CFBundleURLName</key>
-            <string>com.steipete.clawdis.deeplink</string>
-            <key>CFBundleURLSchemes</key>
-            <array>
-                <string>clawdis</string>
-            </array>
-        </dict>
-    </array>
-    <key>ClawdisBuildTimestamp</key>
-    <string>${BUILD_TS}</string>
-    <key>ClawdisGitCommit</key>
-    <string>${GIT_COMMIT}</string>
-    <key>SUFeedURL</key>
-    <string>${SPARKLE_FEED_URL}</string>
-    <key>SUPublicEDKey</key>
-    <string>${SPARKLE_PUBLIC_ED_KEY}</string>
-    <key>SUEnableAutomaticChecks</key>
-    <${AUTO_CHECKS}/>
-    <key>NSUserNotificationUsageDescription</key>
-    <string>Clawdis needs notification permission to show alerts for agent actions.</string>
-    <key>NSScreenCaptureDescription</key>
-    <string>Clawdis captures the screen when the agent needs screenshots for context.</string>
-    <key>NSCameraUsageDescription</key>
-    <string>Clawdis can capture photos or short video clips when requested by the agent.</string>
-    <key>NSMicrophoneUsageDescription</key>
-    <string>Clawdis needs the mic for Voice Wake tests and agent audio capture.</string>
-    <key>NSSpeechRecognitionUsageDescription</key>
-    <string>Clawdis uses speech recognition to detect your Voice Wake trigger phrase.</string>
-    <key>NSAppleEventsUsageDescription</key>
-    <string>Clawdis needs Automation (AppleScript) permission to drive Terminal and other apps for agent actions.</string>
-    <key>NSAppTransportSecurity</key>
-    <dict>
-        <key>NSAllowsArbitraryLoadsInWebContent</key>
-        <true/>
-        <key>NSExceptionDomains</key>
-        <dict>
-            <key>100.100.100.100</key>
-            <dict>
-                <key>NSExceptionAllowsInsecureHTTPLoads</key>
-                <true/>
-                <key>NSIncludesSubdomains</key>
-                <true/>
-            </dict>
-        </dict>
-    </dict>
-</dict>
-</plist>
-PLIST
 
 echo "🚚 Copying binary"
 cp "$BIN" "$APP_ROOT/Contents/MacOS/Clawdis"

src/config/config.test.ts

@@ -16,6 +16,37 @@ async function withTempHome<T>(fn: (home: string) => Promise<T>): Promise<T> {
   }
 }
 
+/**
+ * Helper to test env var overrides. Saves/restores env vars and resets modules.
+ */
+async function withEnvOverride<T>(
+  overrides: Record<string, string | undefined>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const saved: Record<string, string | undefined> = {};
+  for (const key of Object.keys(overrides)) {
+    saved[key] = process.env[key];
+    if (overrides[key] === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = overrides[key];
+    }
+  }
+  vi.resetModules();
+  try {
+    return await fn();
+  } finally {
+    for (const key of Object.keys(saved)) {
+      if (saved[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = saved[key];
+      }
+    }
+    vi.resetModules();
+  }
+}
+
 describe("config identity defaults", () => {
   let previousHome: string | undefined;
 
@@ -174,3 +205,152 @@ describe("config identity defaults", () => {
     });
   });
 });
+
+describe("Nix integration (U3, U5, U9)", () => {
+  describe("U3: isNixMode env var detection", () => {
+    it("isNixMode is false when CLAWDIS_NIX_MODE is not set", async () => {
+      await withEnvOverride({ CLAWDIS_NIX_MODE: undefined }, async () => {
+        const { isNixMode } = await import("./config.js");
+        expect(isNixMode).toBe(false);
+      });
+    });
+
+    it("isNixMode is false when CLAWDIS_NIX_MODE is empty", async () => {
+      await withEnvOverride({ CLAWDIS_NIX_MODE: "" }, async () => {
+        const { isNixMode } = await import("./config.js");
+        expect(isNixMode).toBe(false);
+      });
+    });
+
+    it("isNixMode is false when CLAWDIS_NIX_MODE is not '1'", async () => {
+      await withEnvOverride({ CLAWDIS_NIX_MODE: "true" }, async () => {
+        const { isNixMode } = await import("./config.js");
+        expect(isNixMode).toBe(false);
+      });
+    });
+
+    it("isNixMode is true when CLAWDIS_NIX_MODE=1", async () => {
+      await withEnvOverride({ CLAWDIS_NIX_MODE: "1" }, async () => {
+        const { isNixMode } = await import("./config.js");
+        expect(isNixMode).toBe(true);
+      });
+    });
+  });
+
+  describe("U5: CONFIG_PATH and STATE_DIR env var overrides", () => {
+    it("STATE_DIR_CLAWDIS defaults to ~/.clawdis when env not set", async () => {
+      await withEnvOverride({ CLAWDIS_STATE_DIR: undefined }, async () => {
+        const { STATE_DIR_CLAWDIS } = await import("./config.js");
+        expect(STATE_DIR_CLAWDIS).toMatch(/\.clawdis$/);
+      });
+    });
+
+    it("STATE_DIR_CLAWDIS respects CLAWDIS_STATE_DIR override", async () => {
+      await withEnvOverride(
+        { CLAWDIS_STATE_DIR: "/custom/state/dir" },
+        async () => {
+          const { STATE_DIR_CLAWDIS } = await import("./config.js");
+          expect(STATE_DIR_CLAWDIS).toBe("/custom/state/dir");
+        },
+      );
+    });
+
+    it("CONFIG_PATH_CLAWDIS defaults to ~/.clawdis/clawdis.json when env not set", async () => {
+      await withEnvOverride(
+        { CLAWDIS_CONFIG_PATH: undefined, CLAWDIS_STATE_DIR: undefined },
+        async () => {
+          const { CONFIG_PATH_CLAWDIS } = await import("./config.js");
+          expect(CONFIG_PATH_CLAWDIS).toMatch(/\.clawdis\/clawdis\.json$/);
+        },
+      );
+    });
+
+    it("CONFIG_PATH_CLAWDIS respects CLAWDIS_CONFIG_PATH override", async () => {
+      await withEnvOverride(
+        { CLAWDIS_CONFIG_PATH: "/nix/store/abc/clawdis.json" },
+        async () => {
+          const { CONFIG_PATH_CLAWDIS } = await import("./config.js");
+          expect(CONFIG_PATH_CLAWDIS).toBe("/nix/store/abc/clawdis.json");
+        },
+      );
+    });
+
+    it("CONFIG_PATH_CLAWDIS uses STATE_DIR_CLAWDIS when only state dir is overridden", async () => {
+      await withEnvOverride(
+        {
+          CLAWDIS_CONFIG_PATH: undefined,
+          CLAWDIS_STATE_DIR: "/custom/state",
+        },
+        async () => {
+          const { CONFIG_PATH_CLAWDIS } = await import("./config.js");
+          expect(CONFIG_PATH_CLAWDIS).toBe("/custom/state/clawdis.json");
+        },
+      );
+    });
+  });
+
+  describe("U9: telegram.tokenFile schema validation", () => {
+    it("accepts config with only botToken", async () => {
+      await withTempHome(async (home) => {
+        const configDir = path.join(home, ".clawdis");
+        await fs.mkdir(configDir, { recursive: true });
+        await fs.writeFile(
+          path.join(configDir, "clawdis.json"),
+          JSON.stringify({
+            telegram: { botToken: "123:ABC" },
+          }),
+          "utf-8",
+        );
+
+        vi.resetModules();
+        const { loadConfig } = await import("./config.js");
+        const cfg = loadConfig();
+        expect(cfg.telegram?.botToken).toBe("123:ABC");
+        expect(cfg.telegram?.tokenFile).toBeUndefined();
+      });
+    });
+
+    it("accepts config with only tokenFile", async () => {
+      await withTempHome(async (home) => {
+        const configDir = path.join(home, ".clawdis");
+        await fs.mkdir(configDir, { recursive: true });
+        await fs.writeFile(
+          path.join(configDir, "clawdis.json"),
+          JSON.stringify({
+            telegram: { tokenFile: "/run/agenix/telegram-token" },
+          }),
+          "utf-8",
+        );
+
+        vi.resetModules();
+        const { loadConfig } = await import("./config.js");
+        const cfg = loadConfig();
+        expect(cfg.telegram?.tokenFile).toBe("/run/agenix/telegram-token");
+        expect(cfg.telegram?.botToken).toBeUndefined();
+      });
+    });
+
+    it("accepts config with both botToken and tokenFile", async () => {
+      await withTempHome(async (home) => {
+        const configDir = path.join(home, ".clawdis");
+        await fs.mkdir(configDir, { recursive: true });
+        await fs.writeFile(
+          path.join(configDir, "clawdis.json"),
+          JSON.stringify({
+            telegram: {
+              botToken: "fallback:token",
+              tokenFile: "/run/agenix/telegram-token",
+            },
+          }),
+          "utf-8",
+        );
+
+        vi.resetModules();
+        const { loadConfig } = await import("./config.js");
+        const cfg = loadConfig();
+        expect(cfg.telegram?.botToken).toBe("fallback:token");
+        expect(cfg.telegram?.tokenFile).toBe("/run/agenix/telegram-token");
+      });
+    });
+  });
+});

src/config/config.ts

@@ -7,6 +7,16 @@ import { z } from "zod";
 
 import { parseDurationMs } from "../cli/parse-duration.js";
 
+/**
+ * Nix mode detection: When CLAWDIS_NIX_MODE=1, the gateway is running under Nix.
+ * In this mode:
+ * - No auto-install flows should be attempted
+ * - Missing dependencies should produce actionable Nix-specific error messages
+ * - Config is managed externally (read-only from Nix perspective)
+ */
+export const isNixMode = process.env.CLAWDIS_NIX_MODE === "1";
+
+export type ReplyMode = "text" | "command";
 export type SessionScope = "per-sender" | "global";
 
 export type SessionConfig = {
@@ -131,6 +141,8 @@ export type TelegramConfig = {
   /** If false, do not start the Telegram provider. Default: true. */
   enabled?: boolean;
   botToken?: string;
+  /** Path to file containing bot token (for secret managers like agenix) */
+  tokenFile?: string;
   requireMention?: boolean;
   allowFrom?: Array<string | number>;
   mediaMaxMb?: number;
@@ -395,12 +407,22 @@ export type ClawdisConfig = {
   skills?: Record<string, SkillConfig>;
 };
 
-// New branding path (preferred)
+/**
-export const CONFIG_PATH_CLAWDIS = path.join(
+ * State directory for mutable data (sessions, logs, caches).
-  os.homedir(),
+ * Can be overridden via CLAWDIS_STATE_DIR environment variable.
-  ".clawdis",
+ * Default: ~/.clawdis
-  "clawdis.json",
+ */
-);
+export const STATE_DIR_CLAWDIS =
+  process.env.CLAWDIS_STATE_DIR ?? path.join(os.homedir(), ".clawdis");
+
+/**
+ * Config file path (JSON5).
+ * Can be overridden via CLAWDIS_CONFIG_PATH environment variable.
+ * Default: ~/.clawdis/clawdis.json (or $CLAWDIS_STATE_DIR/clawdis.json)
+ */
+export const CONFIG_PATH_CLAWDIS =
+  process.env.CLAWDIS_CONFIG_PATH ??
+  path.join(STATE_DIR_CLAWDIS, "clawdis.json");
 
 const ModelApiSchema = z.union([
   z.literal("openai-completions"),
@@ -731,6 +753,7 @@ const ClawdisSchema = z.object({
     .object({
       enabled: z.boolean().optional(),
       botToken: z.string().optional(),
+      tokenFile: z.string().optional(),
       requireMention: z.boolean().optional(),
       allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
       mediaMaxMb: z.number().positive().optional(),

src/gateway/server.test.ts

@@ -189,6 +189,7 @@ vi.mock("../config/config.js", () => {
 
   return {
     CONFIG_PATH_CLAWDIS: resolveConfigPath(),
+    isNixMode: false,
     loadConfig: () => ({
       agent: {
         model: "anthropic/claude-opus-4-5",

src/gateway/server.ts

@@ -46,6 +46,7 @@ import { getStatusSummary } from "../commands/status.js";
 import {
   type ClawdisConfig,
   CONFIG_PATH_CLAWDIS,
+  isNixMode,
   loadConfig,
   parseConfigJson5,
   readConfigFileSnapshot,
@@ -1876,6 +1877,30 @@ export async function startGatewayServer(
     };
   };
 
+  /**
+   * Load telegram token with priority: env var > tokenFile > botToken.
+   * tokenFile supports secret managers (e.g., agenix).
+   */
+  const loadTelegramToken = (cfg: ClawdisConfig): string => {
+    if (process.env.TELEGRAM_BOT_TOKEN) {
+      return process.env.TELEGRAM_BOT_TOKEN.trim();
+    }
+    if (cfg.telegram?.tokenFile) {
+      const filePath = cfg.telegram.tokenFile;
+      if (!fs.existsSync(filePath)) {
+        logTelegram.info(`telegram tokenFile not found: ${filePath}`);
+        return "";
+      }
+      try {
+        return fs.readFileSync(filePath, "utf-8").trim();
+      } catch (err) {
+        logTelegram.info(`failed to read telegram tokenFile: ${String(err)}`);
+        return "";
+      }
+    }
+    return cfg.telegram?.botToken?.trim() ?? "";
+  };
+
   const startTelegramProvider = async () => {
     if (telegramTask) return;
     const cfg = loadConfig();
@@ -1888,8 +1913,7 @@ export async function startGatewayServer(
       logTelegram.info("skipping provider start (telegram.enabled=false)");
       return;
     }
-    const telegramToken =
+    const telegramToken = loadTelegramToken(cfg);
-      process.env.TELEGRAM_BOT_TOKEN ?? cfg.telegram?.botToken ?? "";
     if (!telegramToken.trim()) {
       telegramRuntime = {
         ...telegramRuntime,
@@ -6090,6 +6114,9 @@ export async function startGatewayServer(
   });
   log.info(`listening on ws://${bindHost}:${port} (PID ${process.pid})`);
   log.info(`log file: ${getResolvedLoggerSettings().file}`);
+  if (isNixMode) {
+    log.info("gateway: running in Nix mode (config managed externally)");
+  }
   let tailscaleCleanup: (() => Promise<void>) | null = null;
   if (tailscaleMode !== "off") {
     try {