Expose environment selection in app-server thread APIs

codex-rs/app-server-client/src/lib.rs

@@ -1219,6 +1219,7 @@ mod tests {
                     request_id: RequestId::Integer(2),
                     params: ThreadStartParams {
                         ephemeral: Some(true),
+                        environment_id: None,
                         ..ThreadStartParams::default()
                     },
                 })
@@ -1238,6 +1239,7 @@ mod tests {
                 request_id: RequestId::Integer(3),
                 params: ThreadStartParams {
                     ephemeral: Some(true),
+                    environment_id: None,
                     ..ThreadStartParams::default()
                 },
             })

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -352,6 +352,14 @@ client_request_definitions! {
         params: v2::AppsListParams,
         response: v2::AppsListResponse,
     },
+    EnvironmentRegister => "environment/register" {
+        params: v2::EnvironmentRegisterParams,
+        response: v2::EnvironmentRegisterResponse,
+    },
+    EnvironmentList => "environment/list" {
+        params: v2::EnvironmentListParams,
+        response: v2::EnvironmentListResponse,
+    },
     FsReadFile => "fs/readFile" {
         params: v2::FsReadFileParams,
         response: v2::FsReadFileResponse,

codex-rs/app-server-protocol/src/protocol/v2.rs

@@ -2279,6 +2279,53 @@ pub struct FeedbackUploadResponse {
     pub thread_id: String,
 }
 
+/// Register or replace a named execution environment.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentRegisterParams {
+    /// Logical environment identifier used by thread and fs APIs.
+    pub environment_id: String,
+    /// Optional exec-server websocket URL; omit for local execution.
+    #[ts(optional = nullable)]
+    pub exec_server_url: Option<String>,
+}
+
+/// Successful response for `environment/register`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentRegisterResponse {}
+
+/// List named execution environments registered with the app-server.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentListParams {
+    #[ts(optional = nullable)]
+    pub cursor: Option<String>,
+    #[ts(optional = nullable)]
+    pub limit: Option<u32>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentListEntry {
+    pub environment_id: String,
+    #[ts(optional = nullable)]
+    pub exec_server_url: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct EnvironmentListResponse {
+    pub data: Vec<EnvironmentListEntry>,
+    #[ts(optional = nullable)]
+    pub next_cursor: Option<String>,
+}
+
 /// Read a file from the host filesystem.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
@@ -2701,6 +2748,8 @@ pub struct ThreadStartParams {
     pub ephemeral: Option<bool>,
     #[ts(optional = nullable)]
     pub session_start_source: Option<ThreadStartSource>,
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
     #[experimental("thread/start.dynamicTools")]
     #[ts(optional = nullable)]
     pub dynamic_tools: Option<Vec<DynamicToolSpec>>,
@@ -7717,6 +7766,7 @@ mod tests {
                         request_permissions: true,
                         mcp_elicitations: false,
                     }),
+                    environment_id: None,
                     ..Default::default()
                 },
             },
@@ -8690,6 +8740,16 @@ mod tests {
         assert_eq!(serialized_without_override.get("serviceTier"), None);
     }
 
+    #[test]
+    fn thread_start_params_round_trip_environment_id() {
+        let params: ThreadStartParams =
+            serde_json::from_value(json!({ "environmentId": "dev" })).expect("deserialize params");
+        assert_eq!(params.environment_id.as_deref(), Some("dev"));
+
+        let serialized = serde_json::to_value(&params).expect("serialize params");
+        assert_eq!(serialized.get("environmentId"), Some(&json!("dev")));
+    }
+
     #[test]
     fn thread_lifecycle_responses_default_missing_instruction_sources() {
         let response = json!({

codex-rs/app-server-test-client/src/lib.rs

@@ -720,7 +720,8 @@ async fn trigger_zsh_fork_multi_cmd_approval(
 
             let thread_response = client.thread_start(ThreadStartParams {
                 dynamic_tools: dynamic_tools.clone(),
-                ..Default::default()
+                environment_id: None,
+            ..Default::default()
             })?;
             println!("< thread/start response: {thread_response:?}");
 
@@ -958,6 +959,7 @@ async fn send_message_v2_with_policies(
 
             let thread_response = client.thread_start(ThreadStartParams {
                 dynamic_tools: policies.dynamic_tools.clone(),
+                environment_id: None,
                 ..Default::default()
             })?;
             println!("< thread/start response: {thread_response:?}");
@@ -997,6 +999,7 @@ async fn send_follow_up_v2(
 
         let thread_response = client.thread_start(ThreadStartParams {
             dynamic_tools: dynamic_tools.clone(),
+            environment_id: None,
             ..Default::default()
         })?;
         println!("< thread/start response: {thread_response:?}");
@@ -1238,6 +1241,7 @@ fn live_elicitation_timeout_pause(
 
     let thread_response = client.thread_start(ThreadStartParams {
         model: Some(model),
+        environment_id: None,
         ..Default::default()
     })?;
     println!("< thread/start response: {thread_response:?}");

codex-rs/app-server/src/codex_message_processor.rs

@@ -865,6 +865,12 @@ impl CodexMessageProcessor {
             ClientRequest::Initialize { .. } => {
                 panic!("Initialize should be handled in MessageProcessor");
             }
+            ClientRequest::EnvironmentRegister { .. } => {
+                panic!("EnvironmentRegister should be handled in MessageProcessor");
+            }
+            ClientRequest::EnvironmentList { .. } => {
+                panic!("EnvironmentList should be handled in MessageProcessor");
+            }
             // === v2 Thread/Turn APIs ===
             ClientRequest::ThreadStart { request_id, params } => {
                 self.thread_start(
@@ -2274,6 +2280,7 @@ impl CodexMessageProcessor {
             ephemeral,
             session_start_source,
             persist_extended_history,
+            environment_id,
         } = params;
         let mut typesafe_overrides = self.build_thread_config_overrides(
             model,
@@ -2320,6 +2327,7 @@ impl CodexMessageProcessor {
                 service_name,
                 experimental_raw_events,
                 request_trace,
+                environment_id,
             )
             .await;
         };
@@ -2396,6 +2404,7 @@ impl CodexMessageProcessor {
         service_name: Option<String>,
         experimental_raw_events: bool,
         request_trace: Option<W3cTraceContext>,
+        environment_id: Option<String>,
     ) {
         let requested_cwd = typesafe_overrides.cwd.clone();
         let mut config = match derive_config_from_params(
@@ -2543,6 +2552,7 @@ impl CodexMessageProcessor {
                 persist_extended_history,
                 service_name,
                 request_trace,
+                environment_id,
             )
             .instrument(tracing::info_span!(
                 "app_server.thread_start.create_thread",
@@ -6339,7 +6349,12 @@ impl CodexMessageProcessor {
         };
         let skills_manager = self.thread_manager.skills_manager();
         let plugins_manager = self.thread_manager.plugins_manager();
-        let fs = match self.thread_manager.environment_manager().current().await {
+        let fs = match self
+            .thread_manager
+            .environment_manager()
+            .environment(None)
+            .await
+        {
             Ok(Some(environment)) => Some(environment.get_filesystem()),
             Ok(None) => None,
             Err(err) => {

codex-rs/app-server/src/in_process.rs

@@ -786,6 +786,7 @@ mod tests {
                     request_id: RequestId::Integer(2),
                     params: ThreadStartParams {
                         ephemeral: Some(true),
+                        environment_id: None,
                         ..ThreadStartParams::default()
                     },
                 })

codex-rs/app-server/src/message_processor.rs

@@ -36,6 +36,10 @@ use codex_app_server_protocol::ConfigBatchWriteParams;
 use codex_app_server_protocol::ConfigReadParams;
 use codex_app_server_protocol::ConfigValueWriteParams;
 use codex_app_server_protocol::ConfigWarningNotification;
+use codex_app_server_protocol::EnvironmentListParams;
+use codex_app_server_protocol::EnvironmentListResponse;
+use codex_app_server_protocol::EnvironmentRegisterParams;
+use codex_app_server_protocol::EnvironmentRegisterResponse;
 use codex_app_server_protocol::ExperimentalApi;
 use codex_app_server_protocol::ExperimentalFeatureEnablementSetParams;
 use codex_app_server_protocol::ExternalAgentConfigDetectParams;
@@ -64,7 +68,9 @@ use codex_core::ThreadManager;
 use codex_core::config::Config;
 use codex_core::config_loader::CloudRequirementsLoader;
 use codex_core::config_loader::LoaderOverrides;
+use codex_exec_server::EnvironmentConfig;
 use codex_exec_server::EnvironmentManager;
+use codex_exec_server::RegisteredEnvironment;
 use codex_features::Feature;
 use codex_feedback::CodexFeedback;
 use codex_login::AuthManager;
@@ -166,6 +172,7 @@ pub(crate) struct MessageProcessor {
     config_api: ConfigApi,
     external_agent_config_api: ExternalAgentConfigApi,
     fs_api: FsApi,
+    environment_manager: Arc<EnvironmentManager>,
     auth_manager: Arc<AuthManager>,
     analytics_events_client: AnalyticsEventsClient,
     fs_watch_manager: FsWatchManager,
@@ -277,7 +284,7 @@ impl MessageProcessor {
                     .features
                     .enabled(Feature::DefaultModeRequestUserInput),
             },
-            environment_manager,
+            environment_manager.clone(),
             Some(analytics_events_client.clone()),
         ));
         thread_manager
@@ -325,6 +332,7 @@ impl MessageProcessor {
             config_api,
             external_agent_config_api,
             fs_api,
+            environment_manager,
             auth_manager,
             analytics_events_client,
             fs_watch_manager,
@@ -833,6 +841,26 @@ impl MessageProcessor {
                 )
                 .await;
             }
+            ClientRequest::EnvironmentRegister { request_id, params } => {
+                self.handle_environment_register(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::EnvironmentList { request_id, params } => {
+                self.handle_environment_list(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
             ClientRequest::ExperimentalFeatureEnablementSet { request_id, params } => {
                 self.handle_experimental_feature_enablement_set(
                     ConnectionRequestId {
@@ -1138,6 +1166,70 @@ impl MessageProcessor {
         }
     }
 
+    async fn handle_environment_register(
+        &self,
+        request_id: ConnectionRequestId,
+        params: EnvironmentRegisterParams,
+    ) {
+        match self
+            .environment_manager
+            .register_environment(
+                params.environment_id,
+                EnvironmentConfig {
+                    exec_server_url: params.exec_server_url,
+                },
+            )
+            .await
+        {
+            Ok(()) => {
+                self.outgoing
+                    .send_response(request_id, EnvironmentRegisterResponse {})
+                    .await
+            }
+            Err(err) => {
+                self.outgoing
+                    .send_error(
+                        request_id,
+                        JSONRPCErrorError {
+                            code: INVALID_REQUEST_ERROR_CODE,
+                            message: err.to_string(),
+                            data: None,
+                        },
+                    )
+                    .await
+            }
+        }
+    }
+
+    async fn handle_environment_list(
+        &self,
+        request_id: ConnectionRequestId,
+        params: EnvironmentListParams,
+    ) {
+        let (data, next_cursor) = self
+            .environment_manager
+            .list_environments(params.cursor.as_deref(), params.limit)
+            .await;
+        let response = EnvironmentListResponse {
+            data: data
+                .into_iter()
+                .map(
+                    |RegisteredEnvironment {
+                         environment_id,
+                         config,
+                     }| {
+                        codex_app_server_protocol::EnvironmentListEntry {
+                            environment_id,
+                            exec_server_url: config.exec_server_url,
+                        }
+                    },
+                )
+                .collect(),
+            next_cursor,
+        };
+        self.outgoing.send_response(request_id, response).await;
+    }
+
     async fn handle_fs_read_file(&self, request_id: ConnectionRequestId, params: FsReadFileParams) {
         match self.fs_api.read_file(params).await {
             Ok(response) => self.outgoing.send_response(request_id, response).await,

codex-rs/app-server/tests/common/mcp_process.rs

@@ -23,6 +23,8 @@ use codex_app_server_protocol::CommandExecWriteParams;
 use codex_app_server_protocol::ConfigBatchWriteParams;
 use codex_app_server_protocol::ConfigReadParams;
 use codex_app_server_protocol::ConfigValueWriteParams;
+use codex_app_server_protocol::EnvironmentListParams;
+use codex_app_server_protocol::EnvironmentRegisterParams;
 use codex_app_server_protocol::ExperimentalFeatureListParams;
 use codex_app_server_protocol::FeedbackUploadParams;
 use codex_app_server_protocol::FsCopyParams;
@@ -605,6 +607,22 @@ impl McpProcess {
         self.send_request("mock/experimentalMethod", params).await
     }
 
+    pub async fn send_environment_register_request(
+        &mut self,
+        params: EnvironmentRegisterParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("environment/register", params).await
+    }
+
+    pub async fn send_environment_list_request(
+        &mut self,
+        params: EnvironmentListParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("environment/list", params).await
+    }
+
     /// Send a `thread/memoryMode/set` JSON-RPC request (v2, experimental).
     pub async fn send_thread_memory_mode_set_request(
         &mut self,