LM Studio OSS Support (#2312)

## Overview

Adds LM Studio OSS support. Closes #1883


### Changes
This PR enhances the behavior of `--oss` flag to support LM Studio as a
provider. Additionally, it introduces a new flag`--local-provider` which
can take in `lmstudio` or `ollama` as values if the user wants to
explicitly choose which one to use.

If no provider is specified `codex --oss` will auto-select the provider
based on whichever is running.

#### Additional enhancements 
The default can be set using `oss-provider` in config like:

```
oss_provider = "lmstudio"
```

For non-interactive users, they will need to either provide the provider
as an arg or have it in their `config.toml`

### Notes
For best performance, [set the default context
length](https://lmstudio.ai/docs/app/advanced/per-model) for gpt-oss to
the maximum your machine can support

---------

Co-authored-by: Matt Clayton <matt@lmstudio.ai>
Co-authored-by: Eric Traut <etraut@openai.com>

codex-rs/tui/src/cli.rs

@@ -32,12 +32,16 @@ pub struct Cli {
     #[arg(long, short = 'm')]
     pub model: Option<String>,
 
-    /// Convenience flag to select the local open source model provider.
-    /// Equivalent to -c model_provider=oss; verifies a local Ollama server is
-    /// running.
+    /// Convenience flag to select the local open source model provider. Equivalent to -c
+    /// model_provider=oss; verifies a local LM Studio or Ollama server is running.
     #[arg(long = "oss", default_value_t = false)]
     pub oss: bool,
 
+    /// Specify which local provider to use (lmstudio or ollama).
+    /// If not specified with --oss, will use config default or show selection.
+    #[arg(long = "local-provider")]
+    pub oss_provider: Option<String>,
+
     /// Configuration profile from config.toml to specify default options.
     #[arg(long = "profile", short = 'p')]
     pub config_profile: Option<String>,

codex-rs/tui/src/lib.rs

@@ -7,18 +7,21 @@ use additional_dirs::add_dir_warning_message;
 use app::App;
 pub use app::AppExitInfo;
 use codex_app_server_protocol::AuthMode;
+use codex_common::oss::ensure_oss_provider_ready;
+use codex_common::oss::get_default_model_for_oss_provider;
 use codex_core::AuthManager;
-use codex_core::BUILT_IN_OSS_MODEL_PROVIDER_ID;
 use codex_core::CodexAuth;
 use codex_core::INTERACTIVE_SESSION_SOURCES;
 use codex_core::RolloutRecorder;
 use codex_core::auth::enforce_login_restrictions;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
+use codex_core::config::find_codex_home;
+use codex_core::config::load_config_as_toml_with_cli_overrides;
+use codex_core::config::resolve_oss_provider;
 use codex_core::find_conversation_path_by_id_str;
 use codex_core::get_platform_sandbox;
 use codex_core::protocol::AskForApproval;
-use codex_ollama::DEFAULT_OSS_MODEL;
 use codex_protocol::config_types::SandboxMode;
 use opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge;
 use std::fs::OpenOptions;
@@ -56,6 +59,7 @@ mod markdown_render;
 mod markdown_stream;
 mod model_migration;
 pub mod onboarding;
+mod oss_selection;
 mod pager_overlay;
 pub mod public_widgets;
 mod render;
@@ -124,21 +128,75 @@ pub async fn run_main(
 
     // When using `--oss`, let the bootstrapper pick the model (defaulting to
     // gpt-oss:20b) and ensure it is present locally. Also, force the built‑in
+    let raw_overrides = cli.config_overrides.raw_overrides.clone();
     // `oss` model provider.
+    let overrides_cli = codex_common::CliConfigOverrides { raw_overrides };
+    let cli_kv_overrides = match overrides_cli.parse_overrides() {
+        // Parse `-c` overrides from the CLI.
+        Ok(v) => v,
+        #[allow(clippy::print_stderr)]
+        Err(e) => {
+            eprintln!("Error parsing -c overrides: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    // we load config.toml here to determine project state.
+    #[allow(clippy::print_stderr)]
+    let codex_home = match find_codex_home() {
+        Ok(codex_home) => codex_home.to_path_buf(),
+        Err(err) => {
+            eprintln!("Error finding codex home: {err}");
+            std::process::exit(1);
+        }
+    };
+
+    #[allow(clippy::print_stderr)]
+    let config_toml =
+        match load_config_as_toml_with_cli_overrides(&codex_home, cli_kv_overrides.clone()).await {
+            Ok(config_toml) => config_toml,
+            Err(err) => {
+                eprintln!("Error loading config.toml: {err}");
+                std::process::exit(1);
+            }
+        };
+
+    let model_provider_override = if cli.oss {
+        let resolved = resolve_oss_provider(
+            cli.oss_provider.as_deref(),
+            &config_toml,
+            cli.config_profile.clone(),
+        );
+
+        if let Some(provider) = resolved {
+            Some(provider)
+        } else {
+            // No provider configured, prompt the user
+            let provider = oss_selection::select_oss_provider(&codex_home).await?;
+            if provider == "__CANCELLED__" {
+                return Err(std::io::Error::other(
+                    "OSS provider selection was cancelled by user",
+                ));
+            }
+            Some(provider)
+        }
+    } else {
+        None
+    };
+
+    // When using `--oss`, let the bootstrapper pick the model based on selected provider
     let model = if let Some(model) = &cli.model {
         Some(model.clone())
     } else if cli.oss {
-        Some(DEFAULT_OSS_MODEL.to_owned())
+        // Use the provider from model_provider_override
+        model_provider_override
+            .as_ref()
+            .and_then(|provider_id| get_default_model_for_oss_provider(provider_id))
+            .map(std::borrow::ToOwned::to_owned)
     } else {
         None // No model specified, will use the default.
     };
 
-    let model_provider_override = if cli.oss {
-        Some(BUILT_IN_OSS_MODEL_PROVIDER_ID.to_owned())
-    } else {
-        None
-    };
-
     // canonicalize the cwd
     let cwd = cli.cwd.clone().map(|p| p.canonicalize().unwrap_or(p));
     let additional_dirs = cli.add_dir.clone();
@@ -149,7 +207,7 @@ pub async fn run_main(
         approval_policy,
         sandbox_mode,
         cwd,
-        model_provider: model_provider_override,
+        model_provider: model_provider_override.clone(),
         config_profile: cli.config_profile.clone(),
         codex_linux_sandbox_exe,
         base_instructions: None,
@@ -161,16 +219,6 @@ pub async fn run_main(
         experimental_sandbox_command_assessment: None,
         additional_writable_roots: additional_dirs,
     };
-    let raw_overrides = cli.config_overrides.raw_overrides.clone();
-    let overrides_cli = codex_common::CliConfigOverrides { raw_overrides };
-    let cli_kv_overrides = match overrides_cli.parse_overrides() {
-        Ok(v) => v,
-        #[allow(clippy::print_stderr)]
-        Err(e) => {
-            eprintln!("Error parsing -c overrides: {e}");
-            std::process::exit(1);
-        }
-    };
 
     let config = load_config_or_exit(cli_kv_overrides.clone(), overrides.clone()).await;
 
@@ -232,10 +280,19 @@ pub async fn run_main(
         .with_target(false)
         .with_filter(targets);
 
-    if cli.oss {
-        codex_ollama::ensure_oss_ready(&config)
-            .await
-            .map_err(|e| std::io::Error::other(format!("OSS setup failed: {e}")))?;
+    if cli.oss && model_provider_override.is_some() {
+        // We're in the oss section, so provider_id should be Some
+        // Let's handle None case gracefully though just in case
+        let provider_id = match model_provider_override.as_ref() {
+            Some(id) => id,
+            None => {
+                error!("OSS provider unexpectedly not set when oss flag is used");
+                return Err(std::io::Error::other(
+                    "OSS provider not set but oss flag was used",
+                ));
+            }
+        };
+        ensure_oss_provider_ready(provider_id, &config).await?;
     }
 
     let otel = codex_core::otel_init::build_provider(&config, env!("CARGO_PKG_VERSION"));

codex-rs/tui/src/oss_selection.rs

@@ -0,0 +1,369 @@
+use std::io;
+use std::sync::LazyLock;
+
+use codex_core::DEFAULT_LMSTUDIO_PORT;
+use codex_core::DEFAULT_OLLAMA_PORT;
+use codex_core::LMSTUDIO_OSS_PROVIDER_ID;
+use codex_core::OLLAMA_OSS_PROVIDER_ID;
+use codex_core::config::set_default_oss_provider;
+use crossterm::event::Event;
+use crossterm::event::KeyCode;
+use crossterm::event::KeyEvent;
+use crossterm::event::KeyEventKind;
+use crossterm::event::{self};
+use crossterm::execute;
+use crossterm::terminal::EnterAlternateScreen;
+use crossterm::terminal::LeaveAlternateScreen;
+use crossterm::terminal::disable_raw_mode;
+use crossterm::terminal::enable_raw_mode;
+use ratatui::Terminal;
+use ratatui::backend::CrosstermBackend;
+use ratatui::buffer::Buffer;
+use ratatui::layout::Alignment;
+use ratatui::layout::Constraint;
+use ratatui::layout::Direction;
+use ratatui::layout::Layout;
+use ratatui::layout::Margin;
+use ratatui::layout::Rect;
+use ratatui::prelude::*;
+use ratatui::style::Color;
+use ratatui::style::Modifier;
+use ratatui::style::Style;
+use ratatui::text::Line;
+use ratatui::text::Span;
+use ratatui::widgets::Paragraph;
+use ratatui::widgets::Widget;
+use ratatui::widgets::WidgetRef;
+use ratatui::widgets::Wrap;
+use std::time::Duration;
+
+#[derive(Clone)]
+struct ProviderOption {
+    name: String,
+    status: ProviderStatus,
+}
+
+#[derive(Clone)]
+enum ProviderStatus {
+    Running,
+    NotRunning,
+    Unknown,
+}
+
+/// Options displayed in the *select* mode.
+///
+/// The `key` is matched case-insensitively.
+struct SelectOption {
+    label: Line<'static>,
+    description: &'static str,
+    key: KeyCode,
+    provider_id: &'static str,
+}
+
+static OSS_SELECT_OPTIONS: LazyLock<Vec<SelectOption>> = LazyLock::new(|| {
+    vec![
+        SelectOption {
+            label: Line::from(vec!["L".underlined(), "M Studio".into()]),
+            description: "Local LM Studio server (default port 1234)",
+            key: KeyCode::Char('l'),
+            provider_id: LMSTUDIO_OSS_PROVIDER_ID,
+        },
+        SelectOption {
+            label: Line::from(vec!["O".underlined(), "llama".into()]),
+            description: "Local Ollama server (default port 11434)",
+            key: KeyCode::Char('o'),
+            provider_id: OLLAMA_OSS_PROVIDER_ID,
+        },
+    ]
+});
+
+pub struct OssSelectionWidget<'a> {
+    select_options: &'a Vec<SelectOption>,
+    confirmation_prompt: Paragraph<'a>,
+
+    /// Currently selected index in *select* mode.
+    selected_option: usize,
+
+    /// Set to `true` once a decision has been sent – the parent view can then
+    /// remove this widget from its queue.
+    done: bool,
+
+    selection: Option<String>,
+}
+
+impl OssSelectionWidget<'_> {
+    fn new(lmstudio_status: ProviderStatus, ollama_status: ProviderStatus) -> io::Result<Self> {
+        let providers = vec![
+            ProviderOption {
+                name: "LM Studio".to_string(),
+                status: lmstudio_status,
+            },
+            ProviderOption {
+                name: "Ollama".to_string(),
+                status: ollama_status,
+            },
+        ];
+
+        let mut contents: Vec<Line> = vec![
+            Line::from(vec![
+                "? ".fg(Color::Blue),
+                "Select an open-source provider".bold(),
+            ]),
+            Line::from(""),
+            Line::from("  Choose which local AI server to use for your session."),
+            Line::from(""),
+        ];
+
+        // Add status indicators for each provider
+        for provider in &providers {
+            let (status_symbol, status_color) = get_status_symbol_and_color(&provider.status);
+            contents.push(Line::from(vec![
+                Span::raw("  "),
+                Span::styled(status_symbol, Style::default().fg(status_color)),
+                Span::raw(format!(" {} ", provider.name)),
+            ]));
+        }
+        contents.push(Line::from(""));
+        contents.push(Line::from("  ● Running  ○ Not Running").add_modifier(Modifier::DIM));
+
+        contents.push(Line::from(""));
+        contents.push(
+            Line::from("  Press Enter to select • Ctrl+C to exit").add_modifier(Modifier::DIM),
+        );
+
+        let confirmation_prompt = Paragraph::new(contents).wrap(Wrap { trim: false });
+
+        Ok(Self {
+            select_options: &OSS_SELECT_OPTIONS,
+            confirmation_prompt,
+            selected_option: 0,
+            done: false,
+            selection: None,
+        })
+    }
+
+    fn get_confirmation_prompt_height(&self, width: u16) -> u16 {
+        // Should cache this for last value of width.
+        self.confirmation_prompt.line_count(width) as u16
+    }
+
+    /// Process a `KeyEvent` coming from crossterm. Always consumes the event
+    /// while the modal is visible.
+    /// Process a key event originating from crossterm. As the modal fully
+    /// captures input while visible, we don't need to report whether the event
+    /// was consumed—callers can assume it always is.
+    pub fn handle_key_event(&mut self, key: KeyEvent) -> Option<String> {
+        if key.kind == KeyEventKind::Press {
+            self.handle_select_key(key);
+        }
+        if self.done {
+            self.selection.clone()
+        } else {
+            None
+        }
+    }
+
+    /// Normalize a key for comparison.
+    /// - For `KeyCode::Char`, converts to lowercase for case-insensitive matching.
+    /// - Other key codes are returned unchanged.
+    fn normalize_keycode(code: KeyCode) -> KeyCode {
+        match code {
+            KeyCode::Char(c) => KeyCode::Char(c.to_ascii_lowercase()),
+            other => other,
+        }
+    }
+
+    fn handle_select_key(&mut self, key_event: KeyEvent) {
+        match key_event.code {
+            KeyCode::Char('c')
+                if key_event
+                    .modifiers
+                    .contains(crossterm::event::KeyModifiers::CONTROL) =>
+            {
+                self.send_decision("__CANCELLED__".to_string());
+            }
+            KeyCode::Left => {
+                self.selected_option = (self.selected_option + self.select_options.len() - 1)
+                    % self.select_options.len();
+            }
+            KeyCode::Right => {
+                self.selected_option = (self.selected_option + 1) % self.select_options.len();
+            }
+            KeyCode::Enter => {
+                let opt = &self.select_options[self.selected_option];
+                self.send_decision(opt.provider_id.to_string());
+            }
+            KeyCode::Esc => {
+                self.send_decision(LMSTUDIO_OSS_PROVIDER_ID.to_string());
+            }
+            other => {
+                let normalized = Self::normalize_keycode(other);
+                if let Some(opt) = self
+                    .select_options
+                    .iter()
+                    .find(|opt| Self::normalize_keycode(opt.key) == normalized)
+                {
+                    self.send_decision(opt.provider_id.to_string());
+                }
+            }
+        }
+    }
+
+    fn send_decision(&mut self, selection: String) {
+        self.selection = Some(selection);
+        self.done = true;
+    }
+
+    /// Returns `true` once the user has made a decision and the widget no
+    /// longer needs to be displayed.
+    pub fn is_complete(&self) -> bool {
+        self.done
+    }
+
+    pub fn desired_height(&self, width: u16) -> u16 {
+        self.get_confirmation_prompt_height(width) + self.select_options.len() as u16
+    }
+}
+
+impl WidgetRef for &OssSelectionWidget<'_> {
+    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
+        let prompt_height = self.get_confirmation_prompt_height(area.width);
+        let [prompt_chunk, response_chunk] = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints([Constraint::Length(prompt_height), Constraint::Min(0)])
+            .areas(area);
+
+        let lines: Vec<Line> = self
+            .select_options
+            .iter()
+            .enumerate()
+            .map(|(idx, opt)| {
+                let style = if idx == self.selected_option {
+                    Style::new().bg(Color::Cyan).fg(Color::Black)
+                } else {
+                    Style::new().bg(Color::DarkGray)
+                };
+                opt.label.clone().alignment(Alignment::Center).style(style)
+            })
+            .collect();
+
+        let [title_area, button_area, description_area] = Layout::vertical([
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Min(0),
+        ])
+        .areas(response_chunk.inner(Margin::new(1, 0)));
+
+        Line::from("Select provider?").render(title_area, buf);
+
+        self.confirmation_prompt.clone().render(prompt_chunk, buf);
+        let areas = Layout::horizontal(
+            lines
+                .iter()
+                .map(|l| Constraint::Length(l.width() as u16 + 2)),
+        )
+        .spacing(1)
+        .split(button_area);
+        for (idx, area) in areas.iter().enumerate() {
+            let line = &lines[idx];
+            line.render(*area, buf);
+        }
+
+        Line::from(self.select_options[self.selected_option].description)
+            .style(Style::new().italic().fg(Color::DarkGray))
+            .render(description_area.inner(Margin::new(1, 0)), buf);
+    }
+}
+
+fn get_status_symbol_and_color(status: &ProviderStatus) -> (&'static str, Color) {
+    match status {
+        ProviderStatus::Running => ("●", Color::Green),
+        ProviderStatus::NotRunning => ("○", Color::Red),
+        ProviderStatus::Unknown => ("?", Color::Yellow),
+    }
+}
+
+pub async fn select_oss_provider(codex_home: &std::path::Path) -> io::Result<String> {
+    // Check provider statuses first
+    let lmstudio_status = check_lmstudio_status().await;
+    let ollama_status = check_ollama_status().await;
+
+    // Autoselect if only one is running
+    match (&lmstudio_status, &ollama_status) {
+        (ProviderStatus::Running, ProviderStatus::NotRunning) => {
+            let provider = LMSTUDIO_OSS_PROVIDER_ID.to_string();
+            return Ok(provider);
+        }
+        (ProviderStatus::NotRunning, ProviderStatus::Running) => {
+            let provider = OLLAMA_OSS_PROVIDER_ID.to_string();
+            return Ok(provider);
+        }
+        _ => {
+            // Both running or both not running - show UI
+        }
+    }
+
+    let mut widget = OssSelectionWidget::new(lmstudio_status, ollama_status)?;
+
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    let result = loop {
+        terminal.draw(|f| {
+            (&widget).render_ref(f.area(), f.buffer_mut());
+        })?;
+
+        if let Event::Key(key_event) = event::read()?
+            && let Some(selection) = widget.handle_key_event(key_event)
+        {
+            break Ok(selection);
+        }
+    };
+
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+
+    // If the user manually selected an OSS provider, we save it as the
+    // default one to use later.
+    if let Ok(ref provider) = result
+        && let Err(e) = set_default_oss_provider(codex_home, provider)
+    {
+        tracing::warn!("Failed to save OSS provider preference: {e}");
+    }
+
+    result
+}
+
+async fn check_lmstudio_status() -> ProviderStatus {
+    match check_port_status(DEFAULT_LMSTUDIO_PORT).await {
+        Ok(true) => ProviderStatus::Running,
+        Ok(false) => ProviderStatus::NotRunning,
+        Err(_) => ProviderStatus::Unknown,
+    }
+}
+
+async fn check_ollama_status() -> ProviderStatus {
+    match check_port_status(DEFAULT_OLLAMA_PORT).await {
+        Ok(true) => ProviderStatus::Running,
+        Ok(false) => ProviderStatus::NotRunning,
+        Err(_) => ProviderStatus::Unknown,
+    }
+}
+
+async fn check_port_status(port: u16) -> io::Result<bool> {
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(2))
+        .build()
+        .map_err(io::Error::other)?;
+
+    let url = format!("http://localhost:{port}");
+
+    match client.get(&url).send().await {
+        Ok(response) => Ok(response.status().is_success()),
+        Err(_) => Ok(false), // Connection failed = not running
+    }
+}