Add User-Supplied Base URL for Playbooks/Skills

RageLtMan · RageLtMan · commit 88aaaf48ce07 · 2026-03-27T14:02:59.000-04:00
Allow users to specify a custom base URL for downloading rulebooks, skills, and playbooks. This enables private/internal repositories, custom CDNs, and air-gapped environments while maintaining full backward compatibility with Stakpak's default API. Changes: - New config field: rulebook_base_url (optional, defaults to api_endpoint) - New env var: STAKPAK_RULEBOOK_BASE_URL - Separate control plane (api_endpoint) from data plane (rulebook_base_url) - Backward compatible: defaults to https://apiv2.stakpak.dev if not set - All existing configs continue to work without modification Environment Variables: - STAKPAK_RULEBOOK_BASE_URL - Override rulebook base URL globally Config File Examples: [settings] rulebook_base_url = "https://rules.example.com" [profiles.corporate] rulebook_base_url = "http://local-rules:8080"
diff --git a/cli/src/code_index.rs b/cli/src/code_index.rs
@@ -318,6 +318,7 @@ async fn build_local_code_index(
         .map(|api_key| StakpakConfig {
             api_key,
             api_endpoint: app_config.api_endpoint.clone(),
+            rulebook_base_url: app_config.rulebook_base_url.clone(),
         });
 
     let client = AgentClient::new(AgentClientConfig {
@@ -692,6 +693,7 @@ async fn execute_code_index_update(
                 .map(|api_key| StakpakConfig {
                     api_key,
                     api_endpoint: app_config.api_endpoint.clone(),
+                    rulebook_base_url: app_config.rulebook_base_url.clone(),
                 });
 
             let client = AgentClient::new(AgentClientConfig {
diff --git a/cli/src/commands/acp/server.rs b/cli/src/commands/acp/server.rs
@@ -120,6 +120,7 @@ impl StakpakAcpAgent {
             let stakpak = stakpak_api_key.map(|api_key| StakpakConfig {
                 api_key,
                 api_endpoint: config.api_endpoint.clone(),
+                rulebook_base_url: config.rulebook_base_url.clone(),
             });
 
             let client = AgentClient::new(AgentClientConfig {
@@ -1643,6 +1644,7 @@ impl acp::Agent for StakpakAcpAgent {
                 let stakpak = Some(StakpakConfig {
                     api_key: api_key.clone(),
                     api_endpoint: config.api_endpoint.clone(),
+                    rulebook_base_url: config.rulebook_base_url.clone(),
                 });
                 let new_client = AgentClient::new(AgentClientConfig {
                     stakpak,
diff --git a/cli/src/commands/agent/run/mode_async.rs b/cli/src/commands/agent/run/mode_async.rs
@@ -229,8 +229,14 @@ pub async fn run_async(ctx: AppConfig, mut config: RunAsyncConfig) -> Result<Asy
     let mut client_config = AgentClientConfig::new().with_providers(providers);
 
     if let Some(api_key) = ctx.get_stakpak_api_key() {
+        let rulebook_base_url = ctx
+            .rulebook_base_url
+            .clone()
+            .unwrap_or(ctx.api_endpoint.clone());
         client_config = client_config.with_stakpak(
-            stakpak_api::StakpakConfig::new(api_key).with_endpoint(ctx.api_endpoint.clone()),
+            stakpak_api::StakpakConfig::new(api_key)
+                .with_endpoint(ctx.api_endpoint.clone())
+                .with_rulebook_base_url(rulebook_base_url),
         );
     }
     // Pass unified model as smart_model for AgentClient compatibility
diff --git a/cli/src/commands/agent/run/mode_interactive.rs b/cli/src/commands/agent/run/mode_interactive.rs
@@ -350,9 +350,16 @@ pub async fn run_interactive(
             let mut client_config = AgentClientConfig::new().with_providers(providers);
 
             if let Some(ref key) = api_key_for_client {
+                // Use rulebook_base_url from config if set, otherwise fall back to api_endpoint
+                let rulebook_base_url = ctx_clone
+                    .rulebook_base_url
+                    .clone()
+                    .unwrap_or(api_endpoint_for_client.clone());
+
                 client_config = client_config.with_stakpak(
                     stakpak_api::StakpakConfig::new(key.clone())
-                        .with_endpoint(api_endpoint_for_client.clone()),
+                        .with_endpoint(api_endpoint_for_client.clone())
+                        .with_rulebook_base_url(rulebook_base_url),
                 );
             }
             // Pass unified model as smart_model for AgentClient compatibility
@@ -1614,7 +1621,13 @@ pub async fn run_interactive(
             if let Some(api_key) = new_config.get_stakpak_api_key() {
                 new_client_config = new_client_config.with_stakpak(
                     stakpak_api::StakpakConfig::new(api_key)
-                        .with_endpoint(new_config.api_endpoint.clone()),
+                        .with_endpoint(new_config.api_endpoint.clone())
+                        .with_rulebook_base_url(
+                            new_config
+                                .rulebook_base_url
+                                .clone()
+                                .unwrap_or(new_config.api_endpoint.clone()),
+                        ),
                 );
             }
             // Pass unified model as smart_model for AgentClient compatibility
@@ -1685,7 +1698,13 @@ pub async fn run_interactive(
 
         if let Some(api_key) = ctx.get_stakpak_api_key() {
             final_client_config = final_client_config.with_stakpak(
-                stakpak_api::StakpakConfig::new(api_key).with_endpoint(ctx.api_endpoint.clone()),
+                stakpak_api::StakpakConfig::new(api_key)
+                    .with_endpoint(ctx.api_endpoint.clone())
+                    .with_rulebook_base_url(
+                        ctx.rulebook_base_url
+                            .clone()
+                            .unwrap_or(ctx.api_endpoint.clone()),
+                    ),
             );
         }
         // Pass unified model as smart_model for AgentClient compatibility
diff --git a/cli/src/commands/agent/run/profile_switch.rs b/cli/src/commands/agent/run/profile_switch.rs
@@ -36,6 +36,7 @@ pub async fn validate_profile_switch(
             .map(|api_key| StakpakConfig {
                 api_key,
                 api_endpoint: new_config.api_endpoint.clone(),
+                rulebook_base_url: new_config.rulebook_base_url.clone(),
             });
 
         let client = AgentClient::new(AgentClientConfig {
diff --git a/cli/src/commands/mod.rs b/cli/src/commands/mod.rs
@@ -209,6 +209,7 @@ async fn build_agent_client(config: &AppConfig) -> Result<AgentClient, String> {
     let stakpak = config.get_stakpak_api_key().map(|api_key| StakpakConfig {
         api_key,
         api_endpoint: config.api_endpoint.clone(),
+        rulebook_base_url: config.rulebook_base_url.clone(),
     });
 
     AgentClient::new(AgentClientConfig {
diff --git a/cli/src/config/app.rs b/cli/src/config/app.rs
@@ -60,6 +60,9 @@ pub struct AppConfig {
     pub collect_telemetry: Option<bool>,
     /// Editor command
     pub editor: Option<String>,
+    /// Base URL for downloading rulebooks/skills/playbooks
+    /// If not set, api_endpoint is used for content downloads
+    pub rulebook_base_url: Option<String>,
     /// Recently used model IDs (most recent first)
     pub recent_models: Vec<String>,
 }
@@ -154,6 +157,11 @@ impl AppConfig {
             api_key: std::env::var("STAKPAK_API_KEY")
                 .ok()
                 .or(profile_config.api_key),
+            rulebook_base_url: std::env::var("STAKPAK_RULEBOOK_BASE_URL").ok().or(
+                profile_config
+                    .rulebook_base_url
+                    .or(settings.rulebook_base_url),
+            ),
             mcp_server_host: None,
             machine_name: settings.machine_name,
             auto_append_gitignore: settings.auto_append_gitignore,
@@ -964,6 +972,7 @@ impl From<AppConfig> for Settings {
             anonymous_id: config.anonymous_id,
             collect_telemetry: config.collect_telemetry,
             editor: config.editor,
+            rulebook_base_url: config.rulebook_base_url,
         }
     }
 }
@@ -990,6 +999,8 @@ impl From<AppConfig> for ProfileConfig {
             eco_model: None,
             smart_model: None,
             recovery_model: None,
+            // New field for rulebook base URL
+            rulebook_base_url: config.rulebook_base_url,
         }
     }
 }
diff --git a/cli/src/config/file.rs b/cli/src/config/file.rs
@@ -31,6 +31,8 @@ impl Default for ConfigFile {
                 // DEFAULT: Telemetry is OPT-IN, never OPT-OUT
                 collect_telemetry: Some(false),
                 editor: Some("nano".to_string()),
+                // Default rulebook base URL (optional - will fall back to api_endpoint)
+                rulebook_base_url: None,
             },
         }
     }
@@ -51,6 +53,8 @@ impl ConfigFile {
                 // DEFAULT: Telemetry is OPT-IN, never OPT-OUT
                 collect_telemetry: Some(false),
                 editor: Some("nano".to_string()),
+                // Default rulebook base URL (optional - will fall back to api_endpoint)
+                rulebook_base_url: None,
             },
         }
     }
@@ -96,6 +100,7 @@ impl ConfigFile {
         let existing_anonymous_id = self.settings.anonymous_id.clone();
         let existing_collect_telemetry = self.settings.collect_telemetry;
         let existing_editor = self.settings.editor.clone();
+        let existing_rulebook_base_url = self.settings.rulebook_base_url.clone();
 
         self.settings = Settings {
             machine_name: config.machine_name,
@@ -105,6 +110,8 @@ impl ConfigFile {
             // Only set collect_telemetry if config explicitly provides it
             collect_telemetry: config.collect_telemetry.or(existing_collect_telemetry),
             editor: config.editor.or(existing_editor),
+            // Only set rulebook_base_url if config explicitly provides it
+            rulebook_base_url: config.rulebook_base_url.or(existing_rulebook_base_url),
         };
     }
 
@@ -184,4 +191,4 @@ impl From<OldAppConfig> for ConfigFile {
             settings,
         }
     }
-}
+}
diff --git a/cli/src/config/profile.rs b/cli/src/config/profile.rs
@@ -39,6 +39,9 @@ use super::warden::WardenConfig;
 pub struct ProfileConfig {
     /// API endpoint URL
     pub api_endpoint: Option<String>,
+    /// Base URL for downloading rulebooks/skills/playbooks
+    /// If not set, api_endpoint is used for content downloads
+    pub rulebook_base_url: Option<String>,
     /// API key for authentication
     pub api_key: Option<String>,
     /// Provider type (remote or local)
@@ -355,6 +358,10 @@ impl ProfileConfig {
                 .api_endpoint
                 .clone()
                 .or_else(|| other.and_then(|config| config.api_endpoint.clone())),
+            rulebook_base_url: self
+                .rulebook_base_url
+                .clone()
+                .or_else(|| other.and_then(|config| config.rulebook_base_url.clone())),
             api_key: self
                 .api_key
                 .clone()
@@ -591,6 +598,7 @@ impl From<OldAppConfig> for ProfileConfig {
     fn from(old_config: OldAppConfig) -> Self {
         ProfileConfig {
             api_endpoint: Some(old_config.api_endpoint),
+            rulebook_base_url: old_config.rulebook_base_url,
             api_key: old_config.api_key,
             ..ProfileConfig::default()
         }
diff --git a/cli/src/config/types.rs b/cli/src/config/types.rs
@@ -29,12 +29,18 @@ pub struct Settings {
     pub collect_telemetry: Option<bool>,
     /// Preferred external editor (e.g. vim, nano, code)
     pub editor: Option<String>,
+    /// Base URL for downloading rulebooks/skills/playbooks
+    /// If not set, api_endpoint is used for content downloads
+    pub rulebook_base_url: Option<String>,
 }
 
 /// Legacy configuration format for migration purposes.
 #[derive(Deserialize, Clone)]
 pub(crate) struct OldAppConfig {
     pub api_endpoint: String,
+    /// Base URL for downloading rulebooks/skills/playbooks
+    /// If not set, api_endpoint is used for content downloads
+    pub rulebook_base_url: Option<String>,
     pub api_key: Option<String>,
     pub machine_name: Option<String>,
     pub auto_append_gitignore: Option<bool>,
@@ -50,6 +56,7 @@ impl From<OldAppConfig> for Settings {
             // DEFAULT: Telemetry is OPT-IN, never OPT-OUT
             collect_telemetry: Some(false),
             editor: Some("nano".to_string()),
+            rulebook_base_url: old_config.rulebook_base_url,
         }
     }
-}
+}
diff --git a/cli/src/main.rs b/cli/src/main.rs
@@ -242,7 +242,7 @@ async fn main() {
     let should_check_updates = std::env::var("STAKPAK_ENABLE_UPDATES")
         .unwrap_or_else(|_| "0".to_string())
         .eq_ignore_ascii_case("1");
-    
+
     if should_check_updates
         && cli.command.is_none()
         && !cli.r#async
@@ -302,7 +302,7 @@ async fn main() {
             let should_generate_machine_id = std::env::var("STAKPAK_GENERATE_MACHINE_ID")
                 .unwrap_or_else(|_| "0".to_string())
                 .eq_ignore_ascii_case("1");
-            
+
             if should_generate_machine_id && config.machine_name.is_none() {
                 // Generate a random machine name (user opted-in)
                 let random_name = names::Generator::with_naming(Name::Numbered)
@@ -379,9 +379,14 @@ async fn main() {
                 let mut client_config = AgentClientConfig::new().with_providers(providers);
 
                 if let Some(api_key) = config.get_stakpak_api_key() {
+                    let rulebook_base_url = config
+                        .rulebook_base_url
+                        .clone()
+                        .unwrap_or(config.api_endpoint.clone());
                     client_config = client_config.with_stakpak(
                         stakpak_api::StakpakConfig::new(api_key)
-                            .with_endpoint(config.api_endpoint.clone()),
+                            .with_endpoint(config.api_endpoint.clone())
+                            .with_rulebook_base_url(rulebook_base_url),
                     );
                 }
                 // Pass unified model as smart_model for AgentClient compatibility
@@ -1046,4 +1051,4 @@ mod tests {
             .requires_auth()
         );
     }
-}
+}
diff --git a/libs/api/src/client/mod.rs b/libs/api/src/client/mod.rs
@@ -45,20 +45,30 @@ pub struct StakpakConfig {
     pub api_key: String,
     /// Stakpak API endpoint (default: https://apiv2.stakpak.dev)
     pub api_endpoint: String,
+    /// Base URL for downloading rulebooks/skills/playbooks
+    /// If not set, api_endpoint is used for content downloads
+    pub rulebook_base_url: Option<String>,
 }
 
 impl StakpakConfig {
     pub fn new(api_key: impl Into<String>) -> Self {
         Self {
             api_key: api_key.into(),
             api_endpoint: DEFAULT_STAKPAK_ENDPOINT.to_string(),
+            rulebook_base_url: None,
         }
     }
 
     pub fn with_endpoint(mut self, endpoint: impl Into<String>) -> Self {
         self.api_endpoint = endpoint.into();
         self
     }
+
+    /// Set rulebook base URL
+    pub fn with_rulebook_base_url(mut self, url: impl Into<String>) -> Self {
+        self.rulebook_base_url = Some(url.into());
+        self
+    }
 }
 
 /// Configuration for creating an AgentClient
@@ -188,6 +198,7 @@ impl AgentClient {
                     StakpakApiClient::new(&StakpakApiConfig {
                         api_key: stakpak.api_key.clone(),
                         api_endpoint: stakpak.api_endpoint.clone(),
+                        rulebook_base_url: stakpak.rulebook_base_url.clone(),
                     })
                     .map_err(|e| format!("Failed to create Stakpak API client: {}", e))?,
                 )
diff --git a/libs/api/src/stakpak/client.rs b/libs/api/src/stakpak/client.rs
@@ -25,6 +25,7 @@ use uuid::Uuid;
 pub struct StakpakApiClient {
     client: reqwest::Client,
     base_url: String,
+    rulebook_base_url: String,
 }
 
 /// API error response format
@@ -64,9 +65,16 @@ impl StakpakApiClient {
                 .with_timeout(std::time::Duration::from_secs(300)),
         )?;
 
+        // Use rulebook_base_url if provided, otherwise fall back to api_endpoint
+        let rulebook_base_url = config
+            .rulebook_base_url
+            .clone()
+            .unwrap_or_else(|| config.api_endpoint.clone());
+
         Ok(Self {
             client,
             base_url: config.api_endpoint.clone(),
+            rulebook_base_url,
         })
     }
 
@@ -239,11 +247,10 @@ impl StakpakApiClient {
 
     // =========================================================================
     // Rulebook APIs
-    // =========================================================================
 
     /// List all rulebooks
     pub async fn list_rulebooks(&self) -> Result<Vec<ListRuleBook>, String> {
-        let url = format!("{}/v1/rules", self.base_url);
+        let url = format!("{}/v1/rules", self.rulebook_base_url);
         let response = self
             .client
             .get(&url)
@@ -263,7 +270,7 @@ impl StakpakApiClient {
     /// Get a rulebook by URI
     pub async fn get_rulebook_by_uri(&self, uri: &str) -> Result<RuleBook, String> {
         let encoded_uri = urlencoding::encode(uri);
-        let url = format!("{}/v1/rules/{}", self.base_url, encoded_uri);
+        let url = format!("{}/v1/rules/{}", self.rulebook_base_url, encoded_uri);
         let response = self
             .client
             .get(&url)
diff --git a/libs/api/src/stakpak/mod.rs b/libs/api/src/stakpak/mod.rs
diff --git a/libs/api/src/stakpak/storage.rs b/libs/api/src/stakpak/storage.rs

Original file line number	Diff line number	Diff line change
`@@ -60,6 +60,9 @@ pub struct AppConfig {`
`60`	`60`	`pub collect_telemetry: Option<bool>,`
`61`	`61`	`/// Editor command`
`62`	`62`	`pub editor: Option<String>,`
	`63`	`+ /// Base URL for downloading rulebooks/skills/playbooks`
	`64`	`+ /// If not set, api_endpoint is used for content downloads`
	`65`	`+ pub rulebook_base_url: Option<String>,`
`63`	`66`	`/// Recently used model IDs (most recent first)`
`64`	`67`	`pub recent_models: Vec<String>,`
`65`	`68`	`}`
`@@ -154,6 +157,11 @@ impl AppConfig {`
`154`	`157`	`api_key: std::env::var("STAKPAK_API_KEY")`
`155`	`158`	`.ok()`
`156`	`159`	`.or(profile_config.api_key),`
	`160`	`+ rulebook_base_url: std::env::var("STAKPAK_RULEBOOK_BASE_URL").ok().or(`
	`161`	`+ profile_config`
	`162`	`+ .rulebook_base_url`
	`163`	`+ .or(settings.rulebook_base_url),`
	`164`	`+ ),`
`157`	`165`	`mcp_server_host: None,`
`158`	`166`	`machine_name: settings.machine_name,`
`159`	`167`	`auto_append_gitignore: settings.auto_append_gitignore,`
`@@ -964,6 +972,7 @@ impl From<AppConfig> for Settings {`
`964`	`972`	`anonymous_id: config.anonymous_id,`
`965`	`973`	`collect_telemetry: config.collect_telemetry,`
`966`	`974`	`editor: config.editor,`
	`975`	`+ rulebook_base_url: config.rulebook_base_url,`
`967`	`976`	`}`
`968`	`977`	`}`
`969`	`978`	`}`
`@@ -990,6 +999,8 @@ impl From<AppConfig> for ProfileConfig {`
`990`	`999`	`eco_model: None,`
`991`	`1000`	`smart_model: None,`
`992`	`1001`	`recovery_model: None,`
	`1002`	`+ // New field for rulebook base URL`
	`1003`	`+ rulebook_base_url: config.rulebook_base_url,`
`993`	`1004`	`}`
`994`	`1005`	`}`
`995`	`1006`	`}`
Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,8 @@ impl Default for ConfigFile {`
`31`	`31`	`// DEFAULT: Telemetry is OPT-IN, never OPT-OUT`
`32`	`32`	`collect_telemetry: Some(false),`
`33`	`33`	`editor: Some("nano".to_string()),`
	`34`	`+ // Default rulebook base URL (optional - will fall back to api_endpoint)`
	`35`	`+ rulebook_base_url: None,`
`34`	`36`	`},`
`35`	`37`	`}`
`36`	`38`	`}`
`@@ -51,6 +53,8 @@ impl ConfigFile {`
`51`	`53`	`// DEFAULT: Telemetry is OPT-IN, never OPT-OUT`
`52`	`54`	`collect_telemetry: Some(false),`
`53`	`55`	`editor: Some("nano".to_string()),`
	`56`	`+ // Default rulebook base URL (optional - will fall back to api_endpoint)`
	`57`	`+ rulebook_base_url: None,`
`54`	`58`	`},`
`55`	`59`	`}`
`56`	`60`	`}`
`@@ -96,6 +100,7 @@ impl ConfigFile {`
`96`	`100`	`let existing_anonymous_id = self.settings.anonymous_id.clone();`
`97`	`101`	`let existing_collect_telemetry = self.settings.collect_telemetry;`
`98`	`102`	`let existing_editor = self.settings.editor.clone();`
	`103`	`+ let existing_rulebook_base_url = self.settings.rulebook_base_url.clone();`
`99`	`104`
`100`	`105`	`self.settings = Settings {`
`101`	`106`	`machine_name: config.machine_name,`
`@@ -105,6 +110,8 @@ impl ConfigFile {`
`105`	`110`	`// Only set collect_telemetry if config explicitly provides it`
`106`	`111`	`collect_telemetry: config.collect_telemetry.or(existing_collect_telemetry),`
`107`	`112`	`editor: config.editor.or(existing_editor),`
	`113`	`+ // Only set rulebook_base_url if config explicitly provides it`
	`114`	`+ rulebook_base_url: config.rulebook_base_url.or(existing_rulebook_base_url),`
`108`	`115`	`};`
`109`	`116`	`}`
`110`	`117`
`@@ -184,4 +191,4 @@ impl From<OldAppConfig> for ConfigFile {`
`184`	`191`	`settings,`
`185`	`192`	`}`
`186`	`193`	`}`
`187`		`-}`
	`194`	`+}`