From 35677055cf868816422ca46c35efbb14a4f50c0a Mon Sep 17 00:00:00 2001
From: nthmost-orkes <naomi.most@orkes.io>
Date: Thu, 26 Mar 2026 13:54:56 -0700
Subject: [PATCH 1/2] docs: fix install section for Ubuntu/Debian and correct
 UI port
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add venv guidance for Ubuntu 22.04+/Debian 12+ users who hit PEP 668
  error when running pip install system-wide (fixes conductor-oss/getting-started#34,
  conductor-oss/getting-started#35)
- Fix quickstart closing paragraph: localhost:8127 → localhost:8080
  (fixes conductor-oss/getting-started#40)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 886142ac..e2251864 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,14 @@ conductor server start
 pip install conductor-python
 ```
 
+> **Ubuntu / Debian users:** Python 3.12+ on Ubuntu 22.04+ and Debian 12+ blocks system-wide `pip install` by default ([PEP 668](https://peps.python.org/pep-0668/)). Use a virtual environment:
+>
+> ```shell
+> python3 -m venv conductor-env
+> source conductor-env/bin/activate
+> pip install conductor-python
+> ```
+
 ## 60-Second Quickstart
 
 **Step 1: Create a workflow**
@@ -162,7 +170,7 @@ python quickstart.py
 > See [Configuration](#configuration) for details.
 
 That's it — you just defined a worker, built a workflow, and executed it. Open the Conductor UI (default:
-[http://localhost:8127](http://localhost:8127)) to see the execution.
+[http://localhost:8080](http://localhost:8080)) to see the execution.
 
 ---
 

From 9d8220386f46997b964797f4d0498e987c9416dc Mon Sep 17 00:00:00 2001
From: nthmost-orkes <naomi.most@orkes.io>
Date: Thu, 26 Mar 2026 15:59:06 -0700
Subject: [PATCH 2/2] docs: make venv the primary install path (fixes
 getting-started#34)

---
 README.md | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e2251864..4fe864ce 100644
--- a/README.md
+++ b/README.md
@@ -59,16 +59,12 @@ conductor server start
 ## Install the SDK
 
 ```shell
+python3 -m venv conductor-env
+source conductor-env/bin/activate  # Windows: conductor-env\Scripts\activate
 pip install conductor-python
 ```
 
-> **Ubuntu / Debian users:** Python 3.12+ on Ubuntu 22.04+ and Debian 12+ blocks system-wide `pip install` by default ([PEP 668](https://peps.python.org/pep-0668/)). Use a virtual environment:
->
-> ```shell
-> python3 -m venv conductor-env
-> source conductor-env/bin/activate
-> pip install conductor-python
-> ```
+> **Already in a virtual environment?** Skip the `venv` step and run `pip install conductor-python` directly. On macOS, Windows, or in containers where system Python is not locked down, you can also install globally.
 
 ## 60-Second Quickstart