feat: add IRONCLAW_BASE_DIR env var with LazyLock caching

This allows users to place their ironclaw data directory anywhere by setting
the IRONCLAW_BASE_DIR environment variable instead of the hardcoded ~/.ironclaw
path.

Usage:
  IRONCLAW_BASE_DIR=/custom/path ironclaw

Features:
- Value computed once at startup and cached via LazyLock for thread safety
- Empty string or null bytes in env var treated as unset (falls back to default)
- Warns user if home directory cannot be determined (falls back to ./.ironclaw)
- Warns user if IRONCLAW_BASE_DIR contains null bytes

This is useful for development, testing, or running ironclaw in environments
where modifying HOME is not desirable.

Author: ibhagwan

src/bootstrap.rs

@@ -7,13 +7,70 @@
 //! File: `~/.ironclaw/.env` (standard dotenvy format)
 
 use std::path::PathBuf;
+use std::sync::LazyLock;
+
+const IRONCLAW_BASE_DIR_ENV: &str = "IRONCLAW_BASE_DIR";
+
+/// Lazily computed IronClaw base directory, cached for the lifetime of the process.
+static IRONCLAW_BASE_DIR: LazyLock<PathBuf> = LazyLock::new(compute_ironclaw_base_dir);
+
+/// Compute the IronClaw base directory from environment.
+///
+/// This is the underlying implementation used by both the public
+/// `ironclaw_base_dir()` function (which caches the result) and tests
+/// (which need to verify different configurations).
+fn compute_ironclaw_base_dir() -> PathBuf {
+    std::env::var(IRONCLAW_BASE_DIR_ENV)
+        .map(PathBuf::from)
+        .map(|path| {
+            if path.as_os_str().is_empty() {
+                default_base_dir()
+            } else if path.to_string_lossy().contains('\0') {
+                eprintln!("Warning: IRONCLAW_BASE_DIR contains null bytes, using default");
+                default_base_dir()
+            } else {
+                path
+            }
+        })
+        .unwrap_or_else(|_| default_base_dir())
+}
+
+/// Get the default IronClaw base directory (~/.ironclaw).
+///
+/// Logs a warning if the home directory cannot be determined and falls back to
+/// the current directory.
+fn default_base_dir() -> PathBuf {
+    if let Some(home) = dirs::home_dir() {
+        home.join(".ironclaw")
+    } else {
+        eprintln!("Warning: Could not determine home directory, using current directory");
+        PathBuf::from(".").join(".ironclaw")
+    }
+}
+
+/// Get the IronClaw base directory.
+///
+/// Override with `IRONCLAW_BASE_DIR` environment variable.
+/// Defaults to `~/.ironclaw` (or `./.ironclaw` if home directory cannot be determined).
+///
+/// Thread-safe: the value is computed once and cached in a `LazyLock`.
+///
+/// # Environment Variable Behavior
+/// - If `IRONCLAW_BASE_DIR` is set to a non-empty path, that path is used.
+/// - If `IRONCLAW_BASE_DIR` is set to an empty string, it is treated as unset.
+/// - If `IRONCLAW_BASE_DIR` contains null bytes, a warning is printed and the default is used.
+/// - If the home directory cannot be determined, a warning is printed and the current directory is used.
+///
+/// # Returns
+/// A `PathBuf` pointing to the base directory. The path is not validated
+/// for existence.
+pub fn ironclaw_base_dir() -> PathBuf {
+    IRONCLAW_BASE_DIR.clone()
+}
 
 /// Path to the IronClaw-specific `.env` file: `~/.ironclaw/.env`.
 pub fn ironclaw_env_path() -> PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw")
-        .join(".env")
+    ironclaw_base_dir().join(".env")
 }
 
 /// Load env vars from `~/.ironclaw/.env` (in addition to the standard `.env`).
@@ -185,9 +242,7 @@ pub async fn migrate_disk_to_db(
     store: &dyn crate::db::Database,
     user_id: &str,
 ) -> Result<(), MigrationError> {
-    let ironclaw_dir = dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw");
+    let ironclaw_dir = ironclaw_base_dir();
     let legacy_settings_path = ironclaw_dir.join("settings.json");
 
     if !legacy_settings_path.exists() {
@@ -321,8 +376,11 @@ pub enum MigrationError {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::Mutex;
     use tempfile::tempdir;
 
+    static ENV_MUTEX: Mutex<()> = Mutex::new(());
+
     #[test]
     fn test_save_and_load_database_url() {
         let dir = tempdir().unwrap();
@@ -580,4 +638,101 @@ INJECTED="pwned"#;
         assert!(onboard.is_some(), "ONBOARD_COMPLETED must be present");
         assert_eq!(onboard.unwrap().1, "true");
     }
+
+    #[test]
+    fn test_ironclaw_base_dir_default() {
+        // This test must run first (or in isolation) before the LazyLock is initialized.
+        // It verifies that when IRONCLAW_BASE_DIR is not set, the default path is used.
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let old_val = std::env::var("IRONCLAW_BASE_DIR").ok();
+        unsafe { std::env::remove_var("IRONCLAW_BASE_DIR") };
+
+        // Force re-evaluation by calling the computation function directly
+        let path = compute_ironclaw_base_dir();
+        let home = dirs::home_dir().unwrap_or_else(|| std::path::PathBuf::from("."));
+        assert_eq!(path, home.join(".ironclaw"));
+
+        if let Some(val) = old_val {
+            unsafe { std::env::set_var("IRONCLAW_BASE_DIR", val) };
+        }
+    }
+
+    #[test]
+    fn test_ironclaw_base_dir_env_override() {
+        // This test verifies that when IRONCLAW_BASE_DIR is set,
+        // the custom path is used. Must run before LazyLock is initialized.
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let old_val = std::env::var("IRONCLAW_BASE_DIR").ok();
+        unsafe { std::env::set_var("IRONCLAW_BASE_DIR", "/custom/ironclaw/path") };
+
+        // Force re-evaluation by calling the computation function directly
+        let path = compute_ironclaw_base_dir();
+        assert_eq!(path, std::path::PathBuf::from("/custom/ironclaw/path"));
+
+        if let Some(val) = old_val {
+            unsafe { std::env::set_var("IRONCLAW_BASE_DIR", val) };
+        } else {
+            unsafe { std::env::remove_var("IRONCLAW_BASE_DIR") };
+        }
+    }
+
+    #[test]
+    fn test_ironclaw_env_path_uses_base_dir() {
+        // Verifies that ironclaw_env_path correctly joins .env to the base dir.
+        // Uses compute_ironclaw_base_dir directly to avoid LazyLock caching.
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let old_val = std::env::var("IRONCLAW_BASE_DIR").ok();
+        unsafe { std::env::set_var("IRONCLAW_BASE_DIR", "/my/custom/dir") };
+
+        // Test the path construction logic directly
+        let base_path = compute_ironclaw_base_dir();
+        let env_path = base_path.join(".env");
+        assert_eq!(env_path, std::path::PathBuf::from("/my/custom/dir/.env"));
+
+        if let Some(val) = old_val {
+            unsafe { std::env::set_var("IRONCLAW_BASE_DIR", val) };
+        } else {
+            unsafe { std::env::remove_var("IRONCLAW_BASE_DIR") };
+        }
+    }
+
+    #[test]
+    fn test_ironclaw_base_dir_empty_env() {
+        // Verifies that empty IRONCLAW_BASE_DIR falls back to default.
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let old_val = std::env::var("IRONCLAW_BASE_DIR").ok();
+        unsafe { std::env::set_var("IRONCLAW_BASE_DIR", "") };
+
+        // Force re-evaluation by calling the computation function directly
+        let path = compute_ironclaw_base_dir();
+        let home = dirs::home_dir().unwrap_or_else(|| std::path::PathBuf::from("."));
+        assert_eq!(path, home.join(".ironclaw"));
+
+        if let Some(val) = old_val {
+            unsafe { std::env::set_var("IRONCLAW_BASE_DIR", val) };
+        } else {
+            unsafe { std::env::remove_var("IRONCLAW_BASE_DIR") };
+        }
+    }
+
+    #[test]
+    fn test_ironclaw_base_dir_special_chars() {
+        // Verifies that paths with special characters are handled correctly.
+        let _guard = ENV_MUTEX.lock().unwrap();
+        let old_val = std::env::var("IRONCLAW_BASE_DIR").ok();
+        unsafe { std::env::set_var("IRONCLAW_BASE_DIR", "/tmp/test_with-special.chars") };
+
+        // Force re-evaluation by calling the computation function directly
+        let path = compute_ironclaw_base_dir();
+        assert_eq!(
+            path,
+            std::path::PathBuf::from("/tmp/test_with-special.chars")
+        );
+
+        if let Some(val) = old_val {
+            unsafe { std::env::set_var("IRONCLAW_BASE_DIR", val) };
+        } else {
+            unsafe { std::env::remove_var("IRONCLAW_BASE_DIR") };
+        }
+    }
 }

src/channels/repl.rs

@@ -38,6 +38,7 @@ use tokio::sync::mpsc;
 use tokio_stream::wrappers::ReceiverStream;
 
 use crate::agent::truncate_for_preview;
+use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::{Channel, IncomingMessage, MessageStream, OutgoingResponse, StatusUpdate};
 use crate::error::ChannelError;
 
@@ -279,10 +280,7 @@ fn print_help() {
 
 /// Get the history file path (~/.ironclaw/history).
 fn history_path() -> std::path::PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| std::path::PathBuf::from("."))
-        .join(".ironclaw")
-        .join("history")
+    ironclaw_base_dir().join("history")
 }
 
 #[async_trait]

src/channels/signal.rs

@@ -17,6 +17,7 @@ use serde::Deserialize;
 use tokio::sync::RwLock;
 use uuid::Uuid;
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::{Channel, IncomingMessage, MessageStream, OutgoingResponse, StatusUpdate};
 use crate::config::SignalConfig;
 use crate::error::ChannelError;
@@ -557,9 +558,7 @@ impl SignalChannel {
     /// - All paths are within ~/.ironclaw/ sandbox
     fn validate_attachment_paths(paths: &[String]) -> Result<(), ChannelError> {
         // Get the sandbox base directory (same as MessageTool uses)
-        let base_dir = dirs::home_dir()
-            .unwrap_or_else(|| std::path::PathBuf::from("."))
-            .join(".ironclaw");
+        let base_dir = ironclaw_base_dir();
 
         for path in paths {
             crate::tools::builtin::path_utils::validate_path(path, Some(&base_dir)).map_err(

src/channels/wasm/loader.rs

@@ -11,6 +11,7 @@ use std::sync::Arc;
 
 use tokio::fs;
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::wasm::capabilities::ChannelCapabilities;
 use crate::channels::wasm::error::WasmChannelError;
 use crate::channels::wasm::runtime::WasmChannelRuntime;
@@ -349,10 +350,7 @@ pub struct DiscoveredChannel {
 /// Returns ~/.ironclaw/channels/
 #[allow(dead_code)]
 pub fn default_channels_dir() -> PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw")
-        .join("channels")
+    ironclaw_base_dir().join("channels")
 }
 
 #[cfg(test)]

src/channels/web/handlers/static_files.rs

@@ -6,6 +6,7 @@ use axum::{
     response::{Html, IntoResponse},
 };
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::web::types::*;
 
 // --- Static file handlers ---
@@ -71,11 +72,7 @@ async fn serve_project_file(project_id: &str, path: &str) -> axum::response::Res
         return (StatusCode::BAD_REQUEST, "Invalid project ID").into_response();
     }
 
-    let base = dirs::home_dir()
-        .unwrap_or_else(|| std::path::PathBuf::from("."))
-        .join(".ironclaw")
-        .join("projects")
-        .join(project_id);
+    let base = ironclaw_base_dir().join("projects").join(project_id);
 
     let file_path = base.join(path);
 

src/channels/web/server.rs

@@ -26,6 +26,7 @@ use tower_http::set_header::SetResponseHeaderLayer;
 use uuid::Uuid;
 
 use crate::agent::SessionManager;
+use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::IncomingMessage;
 use crate::channels::web::auth::{AuthState, auth_middleware};
 use crate::channels::web::handlers::skills::{
@@ -1921,11 +1922,7 @@ async fn serve_project_file(project_id: &str, path: &str) -> axum::response::Res
         return (StatusCode::BAD_REQUEST, "Invalid project ID").into_response();
     }
 
-    let base = dirs::home_dir()
-        .unwrap_or_else(|| std::path::PathBuf::from("."))
-        .join(".ironclaw")
-        .join("projects")
-        .join(project_id);
+    let base = ironclaw_base_dir().join("projects").join(project_id);
 
     let file_path = base.join(path);
 

src/cli/doctor.rs

@@ -6,6 +6,8 @@
 
 use std::path::PathBuf;
 
+use crate::bootstrap::ironclaw_base_dir;
+
 /// Run all diagnostic checks and print results.
 pub async fn run_doctor_command() -> anyhow::Result<()> {
     println!("IronClaw Doctor");
@@ -195,9 +197,7 @@ async fn try_pg_connect() -> Result<(), String> {
 }
 
 fn check_workspace_dir() -> CheckResult {
-    let dir = dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw");
+    let dir = ironclaw_base_dir();
 
     if dir.exists() {
         if dir.is_dir() {

src/cli/status.rs

@@ -5,6 +5,7 @@
 
 use std::path::PathBuf;
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::settings::Settings;
 
 /// Run the status command, printing system health info.
@@ -206,15 +207,9 @@ fn count_wasm_files(dir: &std::path::Path) -> usize {
 }
 
 fn default_tools_dir() -> PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw")
-        .join("tools")
+    ironclaw_base_dir().join("tools")
 }
 
 fn default_channels_dir() -> PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw")
-        .join("channels")
+    ironclaw_base_dir().join("channels")
 }

src/cli/tool.rs

@@ -9,6 +9,7 @@ use std::sync::Arc;
 use clap::Subcommand;
 use tokio::fs;
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::config::Config;
 #[allow(unused_imports)]
 use crate::db::Database;
@@ -19,9 +20,7 @@ use crate::tools::wasm::{CapabilitiesFile, compute_binary_hash};
 
 /// Default tools directory.
 fn default_tools_dir() -> PathBuf {
-    dirs::home_dir()
-        .map(|h| h.join(".ironclaw").join("tools"))
-        .unwrap_or_else(|| PathBuf::from(".ironclaw/tools"))
+    ironclaw_base_dir().join("tools")
 }
 
 #[derive(Subcommand, Debug, Clone)]

src/config/channels.rs

@@ -2,6 +2,7 @@ use std::path::PathBuf;
 
 use secrecy::SecretString;
 
+use crate::bootstrap::ironclaw_base_dir;
 use crate::config::helpers::{optional_env, parse_bool_env, parse_optional_env};
 use crate::error::ConfigError;
 use crate::settings::Settings;
@@ -193,8 +194,5 @@ impl ChannelsConfig {
 
 /// Get the default channels directory (~/.ironclaw/channels/).
 fn default_channels_dir() -> PathBuf {
-    dirs::home_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join(".ironclaw")
-        .join("channels")
+    ironclaw_base_dir().join("channels")
 }