Skip to content

The open-source app everyone uses to manage agents at work

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.md
index 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.md
index 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 destinations
must resolve entirely to loopback. Public dial targets require TLS trust and
hostname 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-plane
admission 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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());
+ }
+}