Use portless for local dev and agents (#5)

* Use portless for local dev and agents

* save

* save

README.md

@@ -172,11 +172,15 @@ cp .env.example .env.local
 pnpm install
 # Initialize local DB schema (required on a fresh machine)
 pnpm run db:migrate:local
-# This runs in BYPASS_GATEWAY mode so that you don't need to set up the Every App gateway. This is fine for local use.
+# This runs in BYPASS_GATEWAY mode so that you don't need to set up the Every App gateway. This is fine for local use and best for local dev / quick testing since you don't need to access the app through the gatway
 pnpm dev:agents
 ```
 
-App runs on `http://localhost:3001` by default (or `PORT` from `.env.local`).
+`pnpm dev` runs on `http://localhost:3001` by default (or `PORT` from `.env.local`).
+
+`pnpm dev:agents` runs through portless at `http://open-seo.localhost:1355` by default.
+
+When using a git worktree, portless prefixes the branch name, for example `http://feature-name.open-seo.localhost:1355`.
 
 Running locally is the fastest way to test core flows. In the future, local mode will not include some Cloudflare-backed capabilities (for example cron-based rank tracking and infrastructure-powered performance improvements for heavier audits).
 
@@ -194,7 +198,6 @@ pnpm dev:agents
 
 - `pnpm dev:agents` mirrors output to `.logs/dev-server.log` (gitignored).
 - The log file is overwritten on each run.
-- If you need a different port, set `PORT` in `.env.local` and restart.
 
 ### Database Commands
 

package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite dev",
-    "dev:agents": "mkdir -p .logs && BYPASS_GATEWAY_LOCAL_ONLY=true vite dev 2>&1 | tee .logs/dev-server.log",
+    "dev:agents": "mkdir -p .logs && BYPASS_GATEWAY_LOCAL_ONLY=true portless run vite dev 2>&1 | tee .logs/dev-server.log",
     "build": "vite build && tsc --noEmit",
     "lint": "oxlint .",
     "lint:fix": "oxlint . --fix",
@@ -68,6 +68,7 @@
     "drizzle-kit": "^0.31.4",
     "knip": "^5.66.4",
     "oxlint": "^1.50.0",
+    "portless": "^0.5.2",
     "prettier": "^3.6.2",
     "typescript": "^5.9.3",
     "vite": "^7.1.2",

pnpm-lock.yaml

@@ -123,6 +123,9 @@ importers:
       oxlint:
         specifier: ^1.50.0
         version: 1.50.0
+      portless:
+        specifier: ^0.5.2
+        version: 0.5.2
       prettier:
         specifier: ^3.6.2
         version: 3.8.1
@@ -2635,6 +2638,12 @@ packages:
     resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
     engines: {node: '>=12'}
 
+  portless@0.5.2:
+    resolution: {integrity: sha512-LnJvnFUduG4QSIDqc4og9WCLRA6L0+btA96nn6icY6cxyEAR44cnWaIxVzmw7y74KQ+R7zJM1HpenankphympA==}
+    engines: {node: '>=20'}
+    os: [darwin, linux]
+    hasBin: true
+
   postcss@8.5.6:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -5194,6 +5203,10 @@ snapshots:
 
   picomatch@4.0.3: {}
 
+  portless@0.5.2:
+    dependencies:
+      chalk: 5.6.2
+
   postcss@8.5.6:
     dependencies:
       nanoid: 3.3.11