add top-level remote-control command (#21424)

## Summary

`codex --enable remote_control app-server --listen off` is the current
way to start a headless, remote-controllable app-server, but it is hard
to remember and exposes implementation details.

This adds `codex remote-control` as a friendly top-level wrapper for
that flow. The command starts a foreground app-server with local
transports disabled and enables `remote_control` only for that
invocation.

## Changes

- Add a visible `codex remote-control` CLI subcommand.
- Launch app-server with `AppServerTransport::Off`.
- Append `features.remote_control=true` after root feature toggles so
the explicit command wins over `--disable remote_control`.
- Reject root `--remote` / `--remote-auth-token-env`, matching other
non-TUI subcommands.
- Add tests for parsing, launch defaults, override ordering, and remote
flag rejection.

## Verification

- `cargo test -p codex-cli`
- `just fix -p codex-cli`
This commit is contained in:
Owen Lin
2026-05-07 10:17:07 -07:00
committed by GitHub
parent 857e731478
commit 129401df43

View File

@@ -126,6 +126,9 @@ enum Subcommand {
/// [experimental] Run the app server or related tooling.
AppServer(AppServerCommand),
/// [experimental] Start a headless app-server with remote control enabled.
RemoteControl,
/// Launch the Codex desktop app (opens the app installer if missing).
#[cfg(any(target_os = "macos", target_os = "windows"))]
App(app_cmd::AppCommand),
@@ -725,6 +728,14 @@ struct FeatureSetArgs {
feature: String,
}
const REMOTE_CONTROL_FEATURE_OVERRIDE: &str = "features.remote_control=true";
fn enable_remote_control_for_invocation(config_overrides: &mut CliConfigOverrides) {
config_overrides
.raw_overrides
.push(REMOTE_CONTROL_FEATURE_OVERRIDE.to_string());
}
fn stage_str(stage: Stage) -> &'static str {
match stage {
Stage::UnderDevelopment => "under development",
@@ -896,6 +907,24 @@ async fn cli_main(arg0_paths: Arg0DispatchPaths) -> anyhow::Result<()> {
}
}
}
Some(Subcommand::RemoteControl) => {
reject_remote_mode_for_subcommand(
root_remote.as_deref(),
root_remote_auth_token_env.as_deref(),
"remote-control",
)?;
enable_remote_control_for_invocation(&mut root_config_overrides);
codex_app_server::run_main_with_transport(
arg0_paths.clone(),
root_config_overrides,
codex_config::LoaderOverrides::default(),
/*default_analytics_enabled*/ false,
codex_app_server::AppServerTransport::Off,
codex_protocol::protocol::SessionSource::Cli,
codex_app_server::AppServerWebsocketAuthSettings::default(),
)
.await?;
}
#[cfg(any(target_os = "macos", target_os = "windows"))]
Some(Subcommand::App(app_cli)) => {
reject_remote_mode_for_subcommand(
@@ -2276,6 +2305,45 @@ mod tests {
assert!(app_server.analytics_default_enabled);
}
#[test]
fn remote_control_override_is_appended_after_root_toggles() {
let mut config_overrides = CliConfigOverrides::default();
config_overrides
.raw_overrides
.push("features.remote_control=false".to_string());
enable_remote_control_for_invocation(&mut config_overrides);
assert_eq!(
config_overrides.raw_overrides,
vec![
"features.remote_control=false".to_string(),
REMOTE_CONTROL_FEATURE_OVERRIDE.to_string(),
]
);
}
#[test]
fn reject_remote_flag_for_remote_control() {
let cli = MultitoolCli::try_parse_from([
"codex",
"--remote",
"ws://127.0.0.1:1234",
"remote-control",
])
.expect("parse");
assert_matches!(cli.subcommand, Some(Subcommand::RemoteControl));
let err = reject_remote_mode_for_subcommand(
cli.remote.remote.as_deref(),
cli.remote.remote_auth_token_env.as_deref(),
"remote-control",
)
.expect_err("remote-control should reject root --remote");
assert!(err.to_string().contains("remote-control"));
}
#[test]
fn remote_flag_parses_for_interactive_root() {
let cli = MultitoolCli::try_parse_from(["codex", "--remote", "ws://127.0.0.1:4500"])