Add IOTP reset flow, localhost URL UX, and drift warnings

Author: pRizz

README.md

@@ -269,6 +269,12 @@ occ reset container
 # Remove container and volumes (data loss)
 occ reset container --volumes --force
 
+# Reset completed IOTP bootstrap and generate a fresh one-time password
+occ reset iotp
+
+# If bind_address is exposed (for example behind HTTPS reverse proxy), confirm intentionally
+occ reset iotp --force
+
 # Clean bind mount contents (data loss)
 occ mount clean --force
 
@@ -366,6 +372,7 @@ First boot path:
 - Enter that IOTP in the web login page first-time setup panel.
 - Enroll a passkey for the default `opencoder` account.
 - The IOTP is deleted after successful passkey enrollment.
+- To restart first-time onboarding after completion, run `occ reset iotp`.
 - Built-in image users (for example `ubuntu`/`opencoder`) do not disable IOTP bootstrap.
 
 Admin path:

docs/deploy/digitalocean-droplet.md

@@ -156,7 +156,7 @@ Goal: keep opencode on localhost, expose only `80/443` publicly.
 ### 1) Ensure opencode binds to localhost
 
 ```bash
-occ config set bind_address 127.0.0.1
+occ config set bind_address localhost
 occ restart
 ```
 

packages/cli-rust/src/commands/cockpit.rs

@@ -3,6 +3,7 @@
 //! Opens the Cockpit web console in the default browser.
 
 use crate::constants::COCKPIT_EXPOSED;
+use crate::output::localhost_display_addr;
 use anyhow::{Result, bail};
 use clap::Args;
 use console::style;
@@ -59,12 +60,7 @@ pub async fn cmd_cockpit(_args: &CockpitArgs, maybe_host: Option<&str>, quiet: b
 
     let running = container_is_running(&client, CONTAINER_NAME).await?;
     if !running {
-        // For 0.0.0.0 or :: bind addresses, use localhost for display
-        let display_addr = if config.bind_address == "0.0.0.0" || config.bind_address == "::" {
-            "127.0.0.1"
-        } else {
-            &config.bind_address
-        };
+        let display_addr = localhost_display_addr(&config.bind_address);
         bail!(
             "{}\n\n\
              The container is not running. Cockpit runs inside the container.\n\n\
@@ -77,12 +73,7 @@ pub async fn cmd_cockpit(_args: &CockpitArgs, maybe_host: Option<&str>, quiet: b
     }
 
     // Build URL
-    // For 0.0.0.0 or :: bind addresses, use localhost for browser
-    let browser_addr = if config.bind_address == "0.0.0.0" || config.bind_address == "::" {
-        "127.0.0.1"
-    } else {
-        &config.bind_address
-    };
+    let browser_addr = localhost_display_addr(&config.bind_address);
     let url = format!("http://{}:{}", browser_addr, config.cockpit_port);
 
     if !quiet {

packages/cli-rust/src/commands/config/set.rs

@@ -88,7 +88,7 @@ pub fn cmd_config_set(key: &str, value: Option<&str>, quiet: bool, force: bool)
                 eprintln!();
                 eprintln!(
                     "To bind to localhost only: {}",
-                    style("occ config set bind_address 127.0.0.1").cyan()
+                    style("occ config set bind_address localhost").cyan()
                 );
                 eprintln!();
             }

packages/cli-rust/src/commands/container/status.rs

@@ -6,7 +6,7 @@ use crate::commands::runtime_shared::collect_status_view;
 use crate::commands::runtime_shared::status_model::{
     OpencodeHealthStatus, format_broker_health_label,
 };
-use crate::output::state_style;
+use crate::output::{format_service_url, state_style};
 use anyhow::Result;
 use console::style;
 use opencode_cloud_core::docker::get_cli_version;
@@ -55,7 +55,7 @@ pub async fn cmd_status_container(
         "{}",
         format_kv(
             "URL:",
-            style(format!("http://127.0.0.1:{host_port}")).cyan()
+            style(format_service_url(None, "127.0.0.1", host_port)).cyan()
         )
     );
 

packages/cli-rust/src/commands/iotp.rs

@@ -35,13 +35,19 @@ impl IotpSnapshot {
 }
 
 pub(crate) async fn fetch_iotp_snapshot(client: &DockerClient) -> IotpSnapshot {
-    let (output, status) = match exec_command_with_status(
+    query_iotp_snapshot(
         client,
-        CONTAINER_NAME,
         vec![BOOTSTRAP_HELPER_PATH, "status", "--include-secret"],
     )
     .await
-    {
+}
+
+pub(crate) async fn reset_iotp_snapshot(client: &DockerClient) -> IotpSnapshot {
+    query_iotp_snapshot(client, vec![BOOTSTRAP_HELPER_PATH, "reset"]).await
+}
+
+async fn query_iotp_snapshot(client: &DockerClient, command: Vec<&str>) -> IotpSnapshot {
+    let (output, status) = match exec_command_with_status(client, CONTAINER_NAME, command).await {
         Ok(result) => result,
         Err(err) => {
             return IotpSnapshot::unavailable(format!("failed to query bootstrap helper: {err}"));

packages/cli-rust/src/commands/reset/mod.rs

@@ -10,6 +10,7 @@ use crate::commands::disk_usage::{
     DiskUsageReport, HostDiskReport, format_disk_usage_report, format_host_disk_report,
     get_disk_usage_report, get_host_disk_report,
 };
+use crate::commands::iotp::{IotpState, reset_iotp_snapshot};
 use crate::commands::service::{StopSpinnerMessages, stop_service_with_spinner};
 use crate::commands::start::{StartArgs, cmd_start};
 use crate::output::{CommandSpinner, show_docker_error};
@@ -21,8 +22,8 @@ use opencode_cloud_core::config::load_config_or_default;
 use opencode_cloud_core::config::paths::{get_config_dir, get_data_dir};
 use opencode_cloud_core::config::save_config;
 use opencode_cloud_core::docker::{
-    CONTAINER_NAME, DEFAULT_STOP_TIMEOUT_SECS, clear_state, container_exists, remove_all_volumes,
-    remove_images_by_name,
+    CONTAINER_NAME, DEFAULT_STOP_TIMEOUT_SECS, clear_state, container_exists, container_is_running,
+    remove_all_volumes, remove_images_by_name,
 };
 use opencode_cloud_core::platform::{get_service_manager, is_service_registration_supported};
 use std::fs;
@@ -48,6 +49,8 @@ pub enum ResetCommands {
     Container(ResetContainerArgs),
     /// Factory reset the host installation (container, volumes, mounts, config, data)
     Host(ResetHostArgs),
+    /// Reset bootstrap IOTP state and generate a fresh one-time password
+    Iotp(ResetIotpArgs),
 }
 
 /// Arguments for reset container
@@ -90,6 +93,14 @@ pub struct ResetHostArgs {
     pub images: bool,
 }
 
+/// Arguments for reset iotp
+#[derive(Args)]
+pub struct ResetIotpArgs {
+    /// Proceed even when bind_address is non-localhost
+    #[arg(long)]
+    pub force: bool,
+}
+
 pub async fn cmd_reset(
     args: &ResetArgs,
     maybe_host: Option<&str>,
@@ -103,9 +114,86 @@ pub async fn cmd_reset(
         ResetCommands::Host(host_args) => {
             cmd_reset_host(host_args, maybe_host, quiet, verbose).await
         }
+        ResetCommands::Iotp(iotp_args) => cmd_reset_iotp(iotp_args, maybe_host, quiet).await,
     }
 }
 
+async fn cmd_reset_iotp(args: &ResetIotpArgs, maybe_host: Option<&str>, quiet: bool) -> Result<()> {
+    let (client, host_name) = crate::resolve_docker_client(maybe_host).await?;
+    client.verify_connection().await.map_err(|e| {
+        let msg = crate::output::format_docker_error(&e);
+        anyhow!("{msg}")
+    })?;
+
+    if !container_is_running(&client, CONTAINER_NAME).await? {
+        bail!(
+            "Service is not running.\n\
+             Start it first with: {}",
+            style("occ start").cyan()
+        );
+    }
+
+    let config = load_config_or_default()?;
+    if should_block_iotp_reset(&config, args.force) {
+        bail!("{}", iotp_reset_force_message(&config.bind_address));
+    }
+
+    let snapshot = reset_iotp_snapshot(&client).await;
+    if matches!(snapshot.state, IotpState::ActiveUnused)
+        && let Some(iotp) = snapshot.otp.as_deref()
+    {
+        if quiet {
+            println!("{iotp}");
+            return Ok(());
+        }
+
+        println!();
+        println!(
+            "{}",
+            style(crate::format_host_message(
+                host_name.as_deref(),
+                "IOTP reset"
+            ))
+            .cyan()
+            .bold()
+        );
+        println!(
+            "Initial One-Time Password (IOTP): {}",
+            style(iotp).green().bold()
+        );
+        println!(
+            "Enter this in the web login first-time setup panel, then enroll a passkey for {}.",
+            style("opencoder").cyan()
+        );
+        return Ok(());
+    }
+
+    let reason = snapshot
+        .detail
+        .as_deref()
+        .map(str::to_owned)
+        .unwrap_or_else(|| format!("IOTP state is {}", snapshot.state_label));
+    bail!(
+        "IOTP was not reset to an active onboarding state.\n\
+         Reason: {reason}"
+    );
+}
+
+fn iotp_reset_force_message(bind_address: &str) -> String {
+    format!(
+        "Refusing to reset IOTP while bind_address={} is non-localhost.\n\
+         Resetting IOTP reopens first-time onboarding and can expose bootstrap enrollment beyond localhost.\n\
+         If this host is intentionally fronted by a trusted HTTPS reverse proxy with access controls,\n\
+         rerun explicitly with:\n  {}",
+        style(bind_address).cyan(),
+        style("occ reset iotp --force").cyan()
+    )
+}
+
+fn should_block_iotp_reset(config: &opencode_cloud_core::Config, force: bool) -> bool {
+    !config.is_localhost() && !force
+}
+
 /// Capture Docker + host disk usage for reporting before/after destructive steps.
 async fn capture_disk_usage_snapshot(
     client: &opencode_cloud_core::docker::DockerClient,
@@ -640,3 +728,51 @@ fn remove_dir_if_exists(path: Option<PathBuf>, label: &str, quiet: bool, errors:
         println!("Removed {label} directory: {}", style(path.display()).dim());
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn should_block_iotp_reset_for_exposed_bind_without_force() {
+        let config = opencode_cloud_core::Config {
+            bind_address: "0.0.0.0".to_string(),
+            ..Default::default()
+        };
+        assert!(should_block_iotp_reset(&config, false));
+    }
+
+    #[test]
+    fn should_allow_iotp_reset_for_exposed_bind_with_force() {
+        let config = opencode_cloud_core::Config {
+            bind_address: "::".to_string(),
+            ..Default::default()
+        };
+        assert!(!should_block_iotp_reset(&config, true));
+    }
+
+    #[test]
+    fn should_block_iotp_reset_for_specific_non_localhost_without_force() {
+        let config = opencode_cloud_core::Config {
+            bind_address: "192.168.1.10".to_string(),
+            ..Default::default()
+        };
+        assert!(should_block_iotp_reset(&config, false));
+    }
+
+    #[test]
+    fn should_allow_iotp_reset_for_localhost_without_force() {
+        let config = opencode_cloud_core::Config {
+            bind_address: "127.0.0.1".to_string(),
+            ..Default::default()
+        };
+        assert!(!should_block_iotp_reset(&config, false));
+    }
+
+    #[test]
+    fn iotp_reset_force_message_mentions_reverse_proxy_and_force_flag() {
+        let message = iotp_reset_force_message("0.0.0.0");
+        assert!(message.contains("reverse proxy"));
+        assert!(message.contains("occ reset iotp --force"));
+    }
+}

packages/cli-rust/src/commands/restart.rs

@@ -5,7 +5,7 @@
 use crate::commands::runtime_shared::mounts::{collect_bind_mounts, mounts_equal};
 use crate::commands::start::{wait_for_broker_ready, wait_for_service_ready};
 use crate::constants::COCKPIT_EXPOSED;
-use crate::output::{CommandSpinner, format_docker_error, show_docker_error};
+use crate::output::{CommandSpinner, format_docker_error, format_service_url, show_docker_error};
 use anyhow::{Result, anyhow};
 use clap::Args;
 use console::style;
@@ -242,7 +242,7 @@ pub async fn cmd_restart(
             ));
 
             if !quiet {
-                let url = format!("http://{bind_addr}:{port}");
+                let url = format_service_url(None, bind_addr, port);
                 println!();
                 println!("URL:        {}", style(&url).cyan());
                 println!(