Add environment registry support

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,
@@ -1711,14 +1719,16 @@ mod tests {
             request_id: RequestId::Integer(9),
             params: v2::FsGetMetadataParams {
                 path: absolute_path("tmp/example"),
+                environment_id: None,
             },
         };
         assert_eq!(
             json!({
                 "method": "fs/getMetadata",
                 "id": 9,
                 "params": {
-                    "path": absolute_path_string("tmp/example")
+                    "path": absolute_path_string("tmp/example"),
+                    "environmentId": null
                 }
             }),
             serde_json::to_value(&request)?,
@@ -1733,6 +1743,7 @@ mod tests {
             params: v2::FsWatchParams {
                 watch_id: "watch-git".to_string(),
                 path: absolute_path("tmp/repo/.git"),
+                environment_id: None,
             },
         };
         assert_eq!(
@@ -1741,7 +1752,8 @@ mod tests {
                 "id": 10,
                 "params": {
                     "watchId": "watch-git",
-                    "path": absolute_path_string("tmp/repo/.git")
+                    "path": absolute_path_string("tmp/repo/.git"),
+                    "environmentId": null
                 }
             }),
             serde_json::to_value(&request)?,

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

@@ -2279,13 +2279,63 @@ 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")]
 #[ts(export_to = "v2/")]
 pub struct FsReadFileParams {
     /// Absolute path to read.
     pub path: AbsolutePathBuf,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Base64-encoded file contents returned by `fs/readFile`.
@@ -2306,6 +2356,9 @@ pub struct FsWriteFileParams {
     pub path: AbsolutePathBuf,
     /// File contents encoded as base64.
     pub data_base64: String,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Successful response for `fs/writeFile`.
@@ -2324,6 +2377,9 @@ pub struct FsCreateDirectoryParams {
     /// Whether parent directories should also be created. Defaults to `true`.
     #[ts(optional = nullable)]
     pub recursive: Option<bool>,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Successful response for `fs/createDirectory`.
@@ -2339,6 +2395,9 @@ pub struct FsCreateDirectoryResponse {}
 pub struct FsGetMetadataParams {
     /// Absolute path to inspect.
     pub path: AbsolutePathBuf,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Metadata returned by `fs/getMetadata`.
@@ -2367,6 +2426,9 @@ pub struct FsGetMetadataResponse {
 pub struct FsReadDirectoryParams {
     /// Absolute directory path to read.
     pub path: AbsolutePathBuf,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// A directory entry returned by `fs/readDirectory`.
@@ -2404,6 +2466,9 @@ pub struct FsRemoveParams {
     /// Whether missing paths should be ignored. Defaults to `true`.
     #[ts(optional = nullable)]
     pub force: Option<bool>,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Successful response for `fs/remove`.
@@ -2424,6 +2489,9 @@ pub struct FsCopyParams {
     /// Required for directory copies; ignored for file copies.
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]
     pub recursive: bool,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Successful response for `fs/copy`.
@@ -2441,6 +2509,9 @@ pub struct FsWatchParams {
     pub watch_id: String,
     /// Absolute file or directory path to watch.
     pub path: AbsolutePathBuf,
+    /// Optional environment selection. Omit to use the default environment.
+    #[ts(optional = nullable)]
+    pub environment_id: Option<String>,
 }
 
 /// Successful response for `fs/watch`.
@@ -2701,6 +2772,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>>,
@@ -6904,13 +6977,15 @@ mod tests {
     fn fs_read_file_params_round_trip() {
         let params = FsReadFileParams {
             path: absolute_path("tmp/example.txt"),
+            environment_id: Some("dev".to_string()),
         };
 
         let value = serde_json::to_value(&params).expect("serialize fs/readFile params");
         assert_eq!(
             value,
             json!({
                 "path": absolute_path_string("tmp/example.txt"),
+                "environmentId": "dev",
             })
         );
 
@@ -6924,6 +6999,7 @@ mod tests {
         let params = FsCreateDirectoryParams {
             path: absolute_path("tmp/example"),
             recursive: None,
+            environment_id: Some("dev".to_string()),
         };
 
         let value = serde_json::to_value(&params).expect("serialize fs/createDirectory params");
@@ -6932,6 +7008,7 @@ mod tests {
             json!({
                 "path": absolute_path_string("tmp/example"),
                 "recursive": null,
+                "environmentId": "dev",
             })
         );
 
@@ -6945,6 +7022,7 @@ mod tests {
         let params = FsWriteFileParams {
             path: absolute_path("tmp/example.bin"),
             data_base64: "AAE=".to_string(),
+            environment_id: Some("dev".to_string()),
         };
 
         let value = serde_json::to_value(&params).expect("serialize fs/writeFile params");
@@ -6953,6 +7031,7 @@ mod tests {
             json!({
                 "path": absolute_path_string("tmp/example.bin"),
                 "dataBase64": "AAE=",
+                "environmentId": "dev",
             })
         );
 
@@ -6967,6 +7046,7 @@ mod tests {
             source_path: absolute_path("tmp/source"),
             destination_path: absolute_path("tmp/destination"),
             recursive: true,
+            environment_id: Some("dev".to_string()),
         };
 
         let value = serde_json::to_value(&params).expect("serialize fs/copy params");
@@ -6976,6 +7056,7 @@ mod tests {
                 "sourcePath": absolute_path_string("tmp/source"),
                 "destinationPath": absolute_path_string("tmp/destination"),
                 "recursive": true,
+                "environmentId": "dev",
             })
         );
 
@@ -7717,6 +7798,7 @@ mod tests {
                         request_permissions: true,
                         mcp_elicitations: false,
                     }),
+                    environment_id: None,
                     ..Default::default()
                 },
             },
@@ -8690,6 +8772,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) => {