The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Allow configurable Runner listening ports (#15353)
Nicky Leach0fe47882cfcb
diff --git a/doc/architecture/paperclip-runner-daytona-networking.md b/doc/architecture/paperclip-runner-daytona-networking.mdindex 769206bff8..8ab0f2a3dc 100644--- a/doc/architecture/paperclip-runner-daytona-networking.md+++ b/doc/architecture/paperclip-runner-daytona-networking.md@@ -21,7 +21,7 @@ The PRP identity binds company, issue, agent, run, environment lease, runner ins- Allow the sandbox outbound access only to destinations explicitly required by the provider runtime.- Use Daytona's `wss://` preview URL with normal certificate and hostname validation. The preview token is sent only as the `X-Daytona-Preview-Token` header by Paperclip.- Runnerd rejects public plaintext `ws://` destinations. Public dial targets require `wss://` with hostname validation and either the platform trust store or an explicitly staged private CA bundle.-- Listener mode binds only `0.0.0.0:43127`, accepts only the run-specific `/api/runner/v1/connect/:runId` path, and rejects WebSocket extension negotiation. PRP authentication and application-layer secure frames remain mandatory above the preview-proxy hop.+- Listener mode binds only `0.0.0.0`. The optional `--listen-port` selects a port in `1..=65535` and defaults to `43127`. The listener accepts only the run-specific `/api/runner/v1/connect/:runId` path and rejects WebSocket extension negotiation. PRP authentication and application-layer secure frames remain mandatory above the preview-proxy hop.- Do not put the bootstrap ticket in argv, files, provider environment, logs, or model context. Inject it into runnerd's initial environment/secret channel; runnerd already removes it from its environment immediately.- Runnerd is the only process allowed to reach PRP. The provider communicates with runnerd over inherited pipes.diff --git a/packages/paperclip-runner/docs/protocol-compatibility.md b/packages/paperclip-runner/docs/protocol-compatibility.mdindex e462049633..afadb64769 100644--- a/packages/paperclip-runner/docs/protocol-compatibility.md+++ b/packages/paperclip-runner/docs/protocol-compatibility.md@@ -230,9 +230,10 @@ Runnerd build-metadata contract v2 advertises the exact transport inventory:`dial_ws_loopback`, `dial_wss`, and `listen_ws`. Plaintext dial destinationsmust resolve entirely to loopback. Public dial targets require TLS trust andhostname validation; a private CA bundle augments the platform roots and must-be a bounded, private, regular file. Listener mode is fixed to port 43127 and a-single run-bound path. All modes retain the same message/frame bounds and PRP-authentication.+be a bounded, private, regular file. Listener mode binds to `0.0.0.0` and a+single run-bound path. The optional `--listen-port` selects a port in+`1..=65535` and defaults to `43127`. Warm attachments retain the existing+listening port. All modes retain the same message/frame bounds and PRP authentication.These are package-local Durable recovery and transport rules. Control-planeadmission and deployment policy remain separately reviewed work.diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/bin/paperclip-runnerd.rs b/packages/paperclip-runner/runner/crates/runner-core/src/bin/paperclip-runnerd.rsindex 5b1c7231c8..e8b2d5a2f7 100644--- a/packages/paperclip-runner/runner/crates/runner-core/src/bin/paperclip-runnerd.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/src/bin/paperclip-runnerd.rs@@ -261,32 +261,25 @@ fn usize_value(args: &[String], name: &str, default: usize) -> Result<usize, Loc})}-fn run_durable(args: &[String]) -> Result<(), LocalRunnerError> {- let ticket = capture_bootstrap_ticket()- .map_err(|error| LocalRunnerError::invalid(error.to_string()))?- .ok_or_else(|| {- LocalRunnerError::invalid(- "PAPERCLIP_RUNNER_BOOTSTRAP_TICKET is required for durable mode",- )- })?;- let duration = |name: &str, default: u64| {- optional_u64(args, name).map(|value| Duration::from_millis(value.unwrap_or(default)))- };- let state_dir = PathBuf::from(value(args, "--state-dir")?);- let run_id = value(args, "--run-id")?;+fn durable_connect_url(args: &[String], run_id: &str) -> Result<String, LocalRunnerError> {let has_connect = args.iter().any(|argument| argument == "--connect-url");let has_listener = ["--listen-address", "--listen-port", "--listen-path"].iter().any(|name| args.iter().any(|argument| argument == name));- let connect_url = match (has_connect, has_listener) {- (true, false) => value(args, "--connect-url")?,+ match (has_connect, has_listener) {+ (true, false) => value(args, "--connect-url"),(false, true) => {let address = value(args, "--listen-address")?;- let port = value(args, "--listen-port")?;+ let port = optional_u64(args, "--listen-port")?.unwrap_or(43127);+ if !(1..=u16::MAX as u64).contains(&port) {+ return Err(LocalRunnerError::invalid(+ "runner listener port must be in 1..=65535",+ ));+ }let path = value(args, "--listen-path")?;- if address != "0.0.0.0" || port != "43127" {+ if address != "0.0.0.0" {return Err(LocalRunnerError::invalid(- "runner listener requires --listen-address 0.0.0.0 and --listen-port 43127",+ "runner listener requires --listen-address 0.0.0.0",));}if path != format!("/api/runner/v1/connect/{run_id}") {@@ -294,14 +287,30 @@ fn run_durable(args: &[String]) -> Result<(), LocalRunnerError> {"runner listener path must exactly match the configured run",));}- format!("listen://{address}:{port}{path}")+ Ok(format!("listen://{address}:{port}{path}"))}_ => {return Err(LocalRunnerError::invalid("durable runner requires exactly one connect URL or complete listener group",))}+ }+}++fn run_durable(args: &[String]) -> Result<(), LocalRunnerError> {+ let ticket = capture_bootstrap_ticket()+ .map_err(|error| LocalRunnerError::invalid(error.to_string()))?+ .ok_or_else(|| {+ LocalRunnerError::invalid(+ "PAPERCLIP_RUNNER_BOOTSTRAP_TICKET is required for durable mode",+ )+ })?;+ let duration = |name: &str, default: u64| {+ optional_u64(args, name).map(|value| Duration::from_millis(value.unwrap_or(default)))};+ let state_dir = PathBuf::from(value(args, "--state-dir")?);+ let run_id = value(args, "--run-id")?;+ let connect_url = durable_connect_url(args, &run_id)?;let ca_bundle_path = args.iter().any(|argument| argument == "--ca-bundle-path")@@ -394,6 +403,43 @@ fn run_main(args: Vec<String>) -> ExitCode {mod tests {use super::*;+ #[test]+ fn listener_port_is_configurable_and_defaults_to_43127() {+ let base: Vec<String> = [+ "--listen-address",+ "0.0.0.0",+ "--listen-path",+ "/api/runner/v1/connect/run_1",+ ]+ .into_iter()+ .map(str::to_owned)+ .collect();+ assert_eq!(+ durable_connect_url(&base, "run_1").unwrap(),+ "listen://0.0.0.0:43127/api/runner/v1/connect/run_1"+ );+ for port in ["43000", "43999", "65535"] {+ let mut args = base.clone();+ args.extend(["--listen-port".to_owned(), port.to_owned()]);+ assert_eq!(+ durable_connect_url(&args, "run_1").unwrap(),+ format!("listen://0.0.0.0:{port}/api/runner/v1/connect/run_1")+ );+ }+ for port in ["0", "65536", "-1", "invalid", ""] {+ let mut args = base.clone();+ args.extend(["--listen-port".to_owned(), port.to_owned()]);+ assert!(durable_connect_url(&args, "run_1").is_err());+ }+ assert!(durable_connect_url(&base, "another_run").is_err());+ let mut mixed = base.clone();+ mixed.extend([+ "--connect-url".to_owned(),+ "wss://example.test/connect".to_owned(),+ ]);+ assert!(durable_connect_url(&mixed, "run_1").is_err());+ }+#[test]fn build_metadata_advertises_the_remote_transport_contract() {let metadata = build_metadata();diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs b/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rsindex cc4b9d79c1..135a5feb96 100644--- a/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs@@ -189,11 +189,7 @@ impl RunnerTransportEndpoint {"runner_ingress_bind_conflict: listener path is required",)})?;- if authority != "0.0.0.0:43127" {- return Err(DurableRunnerError::invalid(- "runner_ingress_bind_conflict: listener must bind 0.0.0.0:43127",- ));- }+ validate_listener_authority(authority)?;let path = format!("/{path}");validate_listener_path(&path)?;if path != format!("/api/runner/v1/connect/{run_id}") {@@ -203,7 +199,7 @@ impl RunnerTransportEndpoint {}let listener = TcpListener::bind(authority).map_err(|error| {DurableRunnerError::invalid(format!(- "runner_ingress_bind_conflict: failed to bind fixed listener: {error}"+ "runner_ingress_bind_conflict: failed to bind listener: {error}"))})?;listener.set_nonblocking(true).map_err(|error| {@@ -223,15 +219,21 @@ impl RunnerTransportEndpoint {/// `EADDRINUSE`, which would terminate an otherwise healthy warm runner.pub(crate) fn rotate(&mut self, input: &str, run_id: &str) -> Result<(), DurableRunnerError> {if let Some(remainder) = input.strip_prefix("listen://") {- if let Self::Listen { path, .. } = self {+ if let Self::Listen { listener, path } = self {let (authority, next_path) = remainder.split_once('/').ok_or_else(|| {DurableRunnerError::invalid("runner_ingress_bind_conflict: listener path is required",)})?;- if authority != "0.0.0.0:43127" {+ let address = validate_listener_authority(authority)?;+ if listener.local_addr().map_err(|error| {+ DurableRunnerError::invalid(format!(+ "runner listener address unavailable: {error}"+ ))+ })? != address+ {return Err(DurableRunnerError::invalid(- "runner_ingress_bind_conflict: listener must bind 0.0.0.0:43127",+ "runner_ingress_bind_conflict: warm attachment cannot change listener address",));}let next_path = format!("/{next_path}");@@ -382,6 +384,20 @@ impl RunnerTransportEndpoint {}}+fn validate_listener_authority(authority: &str) -> Result<SocketAddr, DurableRunnerError> {+ let address: SocketAddr = authority.parse().map_err(|_| {+ DurableRunnerError::invalid(+ "runner listener address must be 0.0.0.0 with a port in 1..=65535",+ )+ })?;+ if !address.is_ipv4() || !address.ip().is_unspecified() || address.port() == 0 {+ return Err(DurableRunnerError::invalid(+ "runner listener address must be 0.0.0.0 with a port in 1..=65535",+ ));+ }+ Ok(address)+}+fn validate_listener_path(path: &str) -> Result<(), DurableRunnerError> {let run_id = path.strip_prefix("/api/runner/v1/connect/")@@ -2050,6 +2066,66 @@ mod tests {assert!(error.to_string().contains("deadline elapsed"));}+ #[test]+ fn listener_accepts_distinct_ports_and_retains_port_on_warm_attachment() {+ let mut endpoints = [0, 1].map(|_| {+ for _ in 0..10 {+ let reservation = TcpListener::bind("0.0.0.0:0").unwrap();+ let port = reservation.local_addr().unwrap().port();+ drop(reservation);+ match RunnerTransportEndpoint::new(+ &format!("listen://0.0.0.0:{port}/api/runner/v1/connect/run_1"),+ "run_1",+ ) {+ Ok(endpoint) => return endpoint,+ Err(error) => match TcpListener::bind(("0.0.0.0", port)) {+ Err(bind_error) if bind_error.kind() == std::io::ErrorKind::AddrInUse => {+ continue;+ }+ _ => panic!("{error}"),+ },+ }+ }+ panic!("could not acquire an available Runner port");+ });+ let ports = endpoints.each_ref().map(|endpoint| match endpoint {+ RunnerTransportEndpoint::Listen { listener, .. } => {+ listener.local_addr().unwrap().port()+ }+ _ => panic!("expected listener"),+ });+ endpoints[0]+ .rotate(+ &format!("listen://0.0.0.0:{}/api/runner/v1/connect/run_2", ports[0]),+ "run_2",+ )+ .unwrap();+ assert!(endpoints[0]+ .rotate(+ &format!("listen://0.0.0.0:{}/api/runner/v1/connect/run_3", ports[1]),+ "run_3"+ )+ .is_err());+ if let RunnerTransportEndpoint::Listen { listener, path } = &endpoints[0] {+ assert_eq!(listener.local_addr().unwrap().port(), ports[0]);+ assert_eq!(path, "/api/runner/v1/connect/run_2");+ } else {+ panic!("expected listener");+ }+ for authority in [+ "0.0.0.0:0",+ "0.0.0.0:65536",+ "127.0.0.1:43000",+ "[::]:43000",+ "example.test:43000",+ ] {+ assert!(+ validate_listener_authority(authority).is_err(),+ "{authority}"+ );+ }+ }+#[test]fn listener_path_is_exact_and_unambiguous() {validate_listener_path("/api/runner/v1/connect/run_1").unwrap();diff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/listener_port.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/listener_port.rsnew file mode 100644index 0000000000..611e8139f1--- /dev/null+++ b/packages/paperclip-runner/runner/crates/runner-core/tests/listener_port.rs@@ -0,0 +1,106 @@+#![cfg(unix)]++use std::fs;+use std::net::{TcpListener, TcpStream};+use std::os::unix::fs::PermissionsExt;+use std::path::PathBuf;+use std::process::{Child, Command, Stdio};+use std::thread;+use std::time::{Duration, Instant};++struct Runner {+ process: Child,+ directory: PathBuf,+}++impl Drop for Runner {+ fn drop(&mut self) {+ let _ = self.process.kill();+ let _ = self.process.wait();+ let _ = fs::remove_dir_all(&self.directory);+ }+}++#[test]+fn launches_concurrent_runners_on_separate_ports() {+ let mut runners = Vec::new();+ 'attempt: for _ in 0..10 {+ let index = runners.len();+ let reservation = TcpListener::bind("0.0.0.0:0").unwrap();+ let port = reservation.local_addr().unwrap().port();+ drop(reservation);+ let directory =+ std::env::temp_dir().join(format!("runner-listener-{}", uuid::Uuid::new_v4()));+ fs::create_dir(&directory).unwrap();+ fs::set_permissions(&directory, fs::Permissions::from_mode(0o700)).unwrap();+ let run_id = format!("run_{index}");+ let process = Command::new(env!("CARGO_BIN_EXE_paperclip-runnerd"))+ .env(+ "PAPERCLIP_RUNNER_BOOTSTRAP_TICKET",+ "fixture-bootstrap-ticket",+ )+ .args([+ "--listen-address",+ "0.0.0.0",+ "--listen-port",+ &port.to_string(),+ "--listen-path",+ &format!("/api/runner/v1/connect/{run_id}"),+ "--state-dir",+ directory.to_str().unwrap(),+ "--runner-id",+ "runner",+ "--environment-lease-id",+ "lease",+ "--run-id",+ &run_id,+ "--session-id",+ "session",+ "--turn-id",+ "turn",+ "--item-id",+ "item",+ "--runner-version",+ "0.0.0",+ "--runner-digest",+ &format!("sha256:{}", "a".repeat(64)),+ "--max-runtime-ms",+ "10000",+ ])+ .stdout(Stdio::null())+ .spawn()+ .unwrap();+ let mut runner = Runner { process, directory };+ let deadline = Instant::now() + Duration::from_secs(5);+ loop {+ if let Some(status) = runner.process.try_wait().unwrap() {+ match TcpListener::bind(("0.0.0.0", port)) {+ Err(error) if error.kind() == std::io::ErrorKind::AddrInUse => {+ continue 'attempt;+ }+ _ => panic!("Runner exited before listening: {status}"),+ }+ }+ if TcpStream::connect(("127.0.0.1", port)).is_ok() {+ break;+ }+ assert!(+ Instant::now() < deadline,+ "Runner did not bind its selected port"+ );+ thread::sleep(Duration::from_millis(10));+ }+ runners.push(runner);+ if runners.len() == 2 {+ break;+ }+ }+ assert_eq!(+ runners.len(),+ 2,+ "could not acquire two available Runner ports"+ );+ for runner in &mut runners {+ assert!(runner.process.try_wait().unwrap().is_none());+ }+}