From 7ff3592ee62859c7eb4dd2d14e65c6658ddb3942 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 4 Mar 2026 16:56:58 +0000
Subject: [PATCH 1/2] Initial plan


From 6331badbabf7600cc17536b1d6646823b04dd274 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 4 Mar 2026 17:05:40 +0000
Subject: [PATCH 2/2] Add random ports guidance for detached mode with
 --as-system-proxy false

Co-authored-by: garrytrinder <11563347+garrytrinder@users.noreply.github.com>
---
 assets/best-practices.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/assets/best-practices.md b/assets/best-practices.md
index ec22728..faabfcd 100644
--- a/assets/best-practices.md
+++ b/assets/best-practices.md
@@ -57,6 +57,9 @@
 
 - Dev Proxy can run in detached (background) mode (v2.2.0+). This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal.
 - When running in detached mode, use `--output json` to get structured, machine-readable output that can be parsed by scripts and agents.
+- For detached mode and CI/CD scenarios, use `--port 0` (or set `port` to `0` in the configuration file) to let the OS assign a random available port. This avoids port conflicts when running multiple Dev Proxy instances in parallel. Similarly, use `--api-port 0` for the Dev Proxy API port.
+- Combine random ports with `--as-system-proxy false` to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port.
+- When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance.
 
 ## Output format