Add SSH flags to Codex examples and runners

Author: nshkrdotcom

examples/README.md

@@ -33,6 +33,8 @@ applies to Codex CLI subprocesses and MCP HTTP/OAuth flows.
 
 ```bash
 ./examples/run_all.sh
+./examples/run_all.sh --ssh-host example.internal
+./examples/run_all.sh --ssh-host builder@example.internal --ssh-port 2222
 ```
 
 Run the same CLI-backed example set against local Codex OSS + Ollama:
@@ -52,6 +54,27 @@ Run the same CLI-backed example set against local Codex OSS + Ollama:
 The runner checks that the requested Ollama model is installed before starting
 the examples.
 
+SSH routing is explicit and flag-driven. When you pass `--ssh-host`, the
+CLI/app-server examples switch to `execution_surface: :ssh_exec` while keeping
+their existing local default when you omit the flag.
+
+Supported SSH flags for CLI/app-server examples:
+
+- `--ssh-host <host>` or `--ssh-host <user>@<host>`
+- `--ssh-user <user>`
+- `--ssh-port <port>`
+- `--ssh-identity-file <path>`
+
+`--ssh-host` is mutually exclusive with `--ollama`, because `--ollama` is the
+local OSS route and `--ssh-host` is remote subprocess placement.
+
+`./examples/run_all.sh --ssh-host ...` applies only to examples that actually
+run through the Codex CLI execution surface. It does not apply to the direct
+Realtime/Voice examples, and it intentionally skips
+`examples/live_oauth_login.exs` because that example demonstrates local OAuth
+session storage and local browser/device login flow rather than subprocess
+placement.
+
 `gpt-oss:20b` remains the default validated Codex/Ollama example model, but
 the runner also accepts other installed Ollama models such as `llama3.2`.
 Those non-default models may trigger upstream fallback metadata warnings and
@@ -91,6 +114,21 @@ Prereqs:
 
 The `live_*.exs` scripts hit the live Codex CLI (no OPENAI_API_KEY needed if you are authenticated via `codex login`).
 
+Default local usage stays unchanged:
+
+```bash
+mix run examples/live_cli_demo.exs "What is the capital of France?"
+mix run examples/live_app_server_basic.exs "Reply with exactly ok and nothing else."
+```
+
+SSH usage for CLI/app-server examples is explicit:
+
+```bash
+mix run examples/live_cli_demo.exs -- --ssh-host example.internal "What is the capital of France?"
+mix run examples/live_app_server_basic.exs -- --ssh-host builder@example.internal --ssh-port 2222 "Reply with exactly ok and nothing else."
+mix run examples/live_cli_session.exs -- --ssh-host example.internal "Summarize this repository in three bullets."
+```
+
 - `examples/live_cli_demo.exs` — minimal Q&A against the live CLI
 - `examples/live_cli_passthrough.exs` — direct wrappers for `completion`, `features`, `login status`, and arbitrary raw `codex` argv
 - `examples/live_cli_session.exs` — PTY-backed root `codex` prompt mode via `Codex.CLI.interactive/2`
@@ -123,6 +161,11 @@ The `live_*.exs` scripts hit the live Codex CLI (no OPENAI_API_KEY needed if you
 - `examples/live_options_config_overrides.exs` — options-level global config overrides, precedence, runtime validation, and reserved-provider notes
 - `examples/live_parity_and_status.exs` — quick pointers to parity docs/fixtures and CLI availability
 
+`examples/live_oauth_login.exs` remains local-only for its primary flow. The
+OAuth session storage, browser launch, and device-code UX are local host
+concerns, not `execution_surface` concerns, so `--ssh-host` is not documented
+for that script.
+
 ## Realtime Voice Examples (OpenAI Agents SDK)
 
 These examples use the OpenAI Realtime API directly (not via Codex CLI). They demonstrate real-time bidirectional voice interactions:

examples/agent_runner_multi_turn.exs

@@ -1,10 +1,16 @@
 #!/usr/bin/env mix run
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 defmodule Examples.AgentRunner do
   @moduledoc false
 
   def run do
-    {:ok, thread} = Codex.start_thread(%{})
+    {:ok, thread} = Codex.start_thread(Support.codex_options!())
 
     {:ok, result} =
       Codex.AgentRunner.run(thread, "Plan a short checklist",

examples/basic_usage.exs

@@ -1,12 +1,18 @@
 #!/usr/bin/env mix run
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 alias Codex.Items
 
 defmodule Examples.BasicUsage do
   @moduledoc false
 
   def ask_question do
-    with {:ok, thread} <- Codex.start_thread(%{}),
+    with {:ok, thread} <- Codex.start_thread(Support.codex_options!()),
          {:ok, result} <- Codex.Thread.run(thread, "What is a GenServer in Elixir?") do
       IO.puts("Final response:\n#{render_response(result.final_response)}\n")
       IO.puts("Token usage: #{format_usage(result.usage)}")
@@ -16,7 +22,7 @@ defmodule Examples.BasicUsage do
   def list_completed_items do
     prompt = "Explain how Elixir processes work, and give me a simple example"
 
-    with {:ok, thread} <- Codex.start_thread(%{}),
+    with {:ok, thread} <- Codex.start_thread(Support.codex_options!()),
          {:ok, result} <- Codex.Thread.run(thread, prompt) do
       Enum.each(result.events, &print_event/1)
     end

examples/concurrency_and_collaboration.exs

@@ -1,5 +1,11 @@
 #!/usr/bin/env mix run
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 alias Codex.Items
 
 defmodule Examples.Concurrency do
@@ -13,7 +19,7 @@ defmodule Examples.Concurrency do
     tasks =
       Enum.map(files, fn file ->
         Task.Supervisor.async_nolink(supervisor, fn ->
-          {:ok, thread} = Codex.start_thread(%{})
+          {:ok, thread} = Codex.start_thread(Support.codex_options!())
 
           prompt =
             "Give 2 quick risk notes you'd flag for a module like #{file} based only on its path/name. " <>
@@ -40,7 +46,7 @@ defmodule Examples.Concurrency do
       items
       |> Enum.map(fn item ->
         Task.Supervisor.async_nolink(supervisor, fn ->
-          {:ok, thread} = Codex.start_thread(%{})
+          {:ok, thread} = Codex.start_thread(Support.codex_options!())
           prompt = "Process #{item} and summarise it succinctly (1-2 sentences)."
 
           case Codex.Thread.run(thread, prompt, %{timeout_ms: timeout_ms, max_turns: 1}) do
@@ -51,7 +57,7 @@ defmodule Examples.Concurrency do
       end)
       |> await_many_with_progress(timeout_ms: 60_000, tick_ms: 5_000, label: "map-reduce")
 
-    {:ok, thread} = Codex.start_thread(%{})
+    {:ok, thread} = Codex.start_thread(Support.codex_options!())
 
     prompt = """
     Summarise these analyses into a concise checklist:
@@ -65,7 +71,7 @@ defmodule Examples.Concurrency do
 
   def collaboration(file) do
     timeout_ms = 20_000
-    {:ok, analyzer} = Codex.start_thread(%{})
+    {:ok, analyzer} = Codex.start_thread(Support.codex_options!())
 
     {:ok, analysis} =
       Codex.Thread.run(
@@ -75,7 +81,7 @@ defmodule Examples.Concurrency do
         %{timeout_ms: timeout_ms, max_turns: 1}
       )
 
-    {:ok, security} = Codex.start_thread(%{})
+    {:ok, security} = Codex.start_thread(Support.codex_options!())
 
     {:ok, security_review} =
       Codex.Thread.run(
@@ -88,7 +94,7 @@ defmodule Examples.Concurrency do
         %{timeout_ms: timeout_ms, max_turns: 1}
       )
 
-    {:ok, performance} = Codex.start_thread(%{})
+    {:ok, performance} = Codex.start_thread(Support.codex_options!())
 
     {:ok, perf_review} =
       Codex.Thread.run(
@@ -101,7 +107,7 @@ defmodule Examples.Concurrency do
         %{timeout_ms: timeout_ms, max_turns: 1}
       )
 
-    {:ok, synthesizer} = Codex.start_thread(%{})
+    {:ok, synthesizer} = Codex.start_thread(Support.codex_options!())
 
     prompt = """
     Synthesize these reviews into actionable recommendations:

examples/conversation_and_resume.exs

@@ -1,14 +1,20 @@
 #!/usr/bin/env mix run
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 alias Codex.ExamplesSupport
 alias Codex.Items
 
 defmodule Examples.Conversation do
   @moduledoc false
 
   def multi_turn do
-    {:ok, codex_opts} =
-      Codex.Options.new(%{model: ExamplesSupport.example_model()})
+    codex_opts =
+      Support.codex_options!(%{model: ExamplesSupport.example_model()})
 
     {:ok, thread} = Codex.start_thread(codex_opts)
 
@@ -36,8 +42,8 @@ defmodule Examples.Conversation do
   end
 
   def resume_existing(thread_id) do
-    {:ok, codex_opts} =
-      Codex.Options.new(%{model: ExamplesSupport.example_model()})
+    codex_opts =
+      Support.codex_options!(%{model: ExamplesSupport.example_model()})
 
     {:ok, thread} = Codex.resume_thread(thread_id, codex_opts)
 
@@ -48,8 +54,8 @@ defmodule Examples.Conversation do
   end
 
   def save_and_resume_demo do
-    {:ok, codex_opts} =
-      Codex.Options.new(%{model: ExamplesSupport.example_model()})
+    codex_opts =
+      Support.codex_options!(%{model: ExamplesSupport.example_model()})
 
     {:ok, thread} = Codex.start_thread(codex_opts)
     {:ok, result1} = Codex.Thread.run(thread, "Remember the number 42 for me.")

examples/live_app_server_approvals.exs

@@ -1,5 +1,11 @@
 Mix.Task.run("app.start")
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 alias Codex.AppServer.ApprovalDecision
 alias Codex.Auth
 alias Codex.Config.LayerStack
@@ -43,17 +49,13 @@ defmodule CodexExamples.LiveAppServerApprovals do
         values -> Enum.join(values, " ")
       end
 
-    with {:ok, codex_path} <- fetch_codex_path(),
-         :ok <- ensure_app_server_supported(codex_path),
+    with {:ok, codex_opts} <- Support.codex_options(%{}, missing_cli: :skip),
+         :ok <- Support.ensure_app_server_supported(codex_opts),
          {:ok, fixture} <- build_demo_fixture() do
       try do
         permissions_prompt = permissions_prompt(fixture)
 
-        with {:ok, codex_opts} <-
-               Codex.Options.new(%{
-                 codex_path_override: codex_path
-               }),
-             {:ok, conn, experimental_api?, init_fallback_reason} <-
+        with {:ok, conn, experimental_api?, init_fallback_reason} <-
                connect_for_approvals_demo(codex_opts, fixture) do
           try do
             parent = self()

examples/live_app_server_basic.exs

@@ -1,5 +1,11 @@
 Mix.Task.run("app.start")
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 alias Codex.Items.AgentMessage
 
 defmodule CodexExamples.LiveAppServerBasic do
@@ -24,13 +30,9 @@ defmodule CodexExamples.LiveAppServerBasic do
         values -> Enum.join(values, " ")
       end
 
-    with {:ok, codex_path} <- fetch_codex_path(),
-         :ok <- ensure_app_server_supported(codex_path),
-         :ok <- ensure_auth_available(),
-         {:ok, codex_opts} <-
-           Codex.Options.new(%{
-             codex_path_override: codex_path
-           }),
+    with {:ok, codex_opts} <- Support.codex_options(%{}, missing_cli: :skip),
+         :ok <- Support.ensure_auth_available(),
+         :ok <- Support.ensure_app_server_supported(codex_opts),
          {:ok, conn} <- Codex.AppServer.connect(codex_opts, init_timeout_ms: 30_000) do
       try do
         personality = :friendly

examples/live_app_server_filesystem.exs

@@ -1,5 +1,11 @@
 Mix.Task.run("app.start")
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 defmodule CodexExamples.LiveAppServerFilesystem do
   @moduledoc false
 
@@ -19,13 +25,9 @@ defmodule CodexExamples.LiveAppServerFilesystem do
   end
 
   defp run do
-    with {:ok, codex_path} <- fetch_codex_path(),
-         :ok <- ensure_app_server_supported(codex_path),
-         :ok <- ensure_auth_available(),
-         {:ok, codex_opts} <-
-           Codex.Options.new(%{
-             codex_path_override: codex_path
-           }),
+    with {:ok, codex_opts} <- Support.codex_options(%{}, missing_cli: :skip),
+         :ok <- Support.ensure_auth_available(),
+         :ok <- Support.ensure_app_server_supported(codex_opts),
          {:ok, conn} <- Codex.AppServer.connect(codex_opts, init_timeout_ms: 30_000) do
       root =
         Path.join(

examples/live_app_server_mcp.exs

@@ -1,16 +1,17 @@
 Mix.Task.run("app.start")
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 defmodule CodexExamples.LiveAppServerMcp do
   @moduledoc false
 
   def main(_argv) do
-    codex_path = fetch_codex_path!()
-    ensure_app_server_supported!(codex_path)
-
-    {:ok, codex_opts} =
-      Codex.Options.new(%{
-        codex_path_override: codex_path
-      })
+    codex_opts = Support.codex_options!()
+    :ok = Support.ensure_app_server_supported(codex_opts)
 
     {:ok, conn} = Codex.AppServer.connect(codex_opts, init_timeout_ms: 30_000)
 

examples/live_app_server_plugins.exs

@@ -1,5 +1,11 @@
 Mix.Task.run("app.start")
 
+Code.require_file(Path.expand("support/example_helper.exs", __DIR__))
+
+alias CodexExamples.Support
+
+Support.init!()
+
 defmodule CodexExamples.LiveAppServerPlugins do
   @moduledoc false
 
@@ -19,15 +25,11 @@ defmodule CodexExamples.LiveAppServerPlugins do
   end
 
   defp run do
-    with {:ok, codex_path} <- fetch_codex_path(),
-         :ok <- ensure_app_server_supported(codex_path),
+    with {:ok, codex_opts} <- Support.codex_options(%{}, missing_cli: :skip),
+         :ok <- Support.ensure_app_server_supported(codex_opts),
          {:ok, fixture} <- build_demo_plugin_fixture() do
       try do
-        with {:ok, codex_opts} <-
-               Codex.Options.new(%{
-                 codex_path_override: codex_path
-               }),
-             {:ok, conn} <-
+        with {:ok, conn} <-
                Codex.AppServer.connect(codex_opts,
                  cwd: fixture.repo_root,
                  process_env: isolated_process_env(fixture),