chore: fix local dev server port assignments

[michaelmagan]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
showcase	Ready	Preview, Comment	Jan 8, 2026 0:16am
tambo-docs	Ready	Preview, Comment	Jan 8, 2026 0:16am

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
cloud	Ignored	Preview	Jan 8, 2026 0:16am

[alecf]

drive by comment:

1. I really like the idea of standardizing on ports so docs isn't starting on port 3000, etc.. what if we standardized on totally separate ports that weren't 3000-based so we don't collide with other projects?
2. personally I really hate scripts that kill processes without me asking!
3. even if we have a script that does that, I believe the params to lsof are different on linux vs macos

Claude code had a fun suggestion with a little easter egg: use 8260, 8261, etc - the 826- prefix is TAM on a phone keypad!

[michaelmagan]

1. I had the same idea… I'm down. I think it would make development easier vs. everything trying to be on 3000… plus it being the default for next projects.
2. Yeah I can remove that. It's a little aggressive. I was a little iffy on it myself.
3. Good point!
   
   Haha I also had a simlar idea if I were going to make custom ports.

[michaelmagan]

@CharlieHelps can you make these updates. 1. set ports to 826* instead of 300* 2. remove the kill process. Just assume they have killed the process before running again (fixes the lsof, issue).

[charliecreates]

Investigating this PR now and I’m likely to update the dev server scripts to use the 826* ports and drop the explicit kill-process step as requested.

Updated: Jan 5, 20:13 UTC
I’m working and can’t be interrupted or see replies—feel free to start another task with me while I finish.

[charliecreates]

Expand this to see my work.

• Scanned apps/web for usages of NEXT_PUBLIC_TAMBO_API_URL, TAMBO_API_URL, and localhost ports, confirming the frontend relies on process.env.NEXT_PUBLIC_TAMBO_API_URL and doesn’t hardcode API ports, while tests (e.g. apps/web/lib/utils.test.ts, apps/web/lib/urlSecurity.test.ts) still treat http://localhost:3000 as the canonical app URL.
• Cataloged docs and examples (apps/web/.env.example, apps/web/README.md, apps/web/app/blog/AGENTS.md, apps/web/components/sections/*, and multiple AGENTS.md files) that explicitly document http://localhost:3000/3001 so they can be aligned with the new dev ports.
• Verified apps/api/.env.example currently documents PORT=8261 as the default local API port, keeping it aligned with the updated dev server configuration.
• Updated scripts/dev-local.sh to stop killing processes on startup and to advertise the new dev ports (8260 web, 8261 api, 8262 showcase, 8263 docs) while keeping the existing Supabase URL intact.
• Changed dev scripts in docs/package.json, showcase/package.json, and apps/web/package.json so the Next.js dev servers now run on ports 8263, 8262, and 8260 instead of the old 3003/3002/3000 defaults.
• Adjusted apps/web/.env.example so NEXT_PUBLIC_TAMBO_API_URL points to http://localhost:8261 and NEXTAUTH_URL points to http://localhost:8260, matching the new local web/api ports.
• Updated supabase/config.toml auth settings so site_url and additional_redirect_urls all reference http://localhost:8260 (and https://127.0.0.1:8260) instead of the old 3000 URLs, and added a comment reminding future changes to stay in sync with apps/web and OAuth provider redirect URIs.
• Ran npm test, npm run lint, and npm run check-types from the repo root on magan/dev-server-setup, confirming Jest, ESLint, and TypeScript checks are green for the 826x-port configuration in PR #1635.
• Implemented a safer, cross-platform port check loop in scripts/dev-local.sh using a small python3 socket bind probe to fail fast with a clear message when ports 8260–8263 are already in use, without auto-killing any processes.
• Committed and pushed these follow-up changes as chore: fail fast if dev ports are in use (2224101b) to the magan/dev-server-setup branch referenced by PR #1635.

[charliecreates]

#1635 (comment)

Updated the local dev port scheme to 826* and removed the “kill processes” behavior. scripts/dev-local.sh now just fails fast if any of the ports are already in use (no lsof usage).

Changes

• Switched dev ports to:
  • Web: 8260 (apps/web/package.json)
  • API: 8261 (apps/api/.env.example, and default fallback in apps/api/src/main.ts)
  • Showcase: 8262 (showcase/package.json)
  • Docs: 8263 (docs/package.json)
• Updated local env/examples to match:
  • apps/web/.env.example (NEXTAUTH_URL, NEXT_PUBLIC_TAMBO_API_URL)
  • supabase/config.toml (site_url, additional_redirect_urls)
• Removed port-killing from scripts/dev-local.sh; added a small python3 bind-check so it errors clearly if a port is occupied.

Commits:

• 16a75fab
• 2224101b

Verification

# ESLint: 13/13 tasks successful
npm run lint

# TypeScript: 13/13 tasks successful
npm run check-types

# Tests: 9/9 tasks successful
npm test

reviewChanges skipped: apps/api/src/main.ts centralizing the default port constant — keeping the diff minimal per the request (no config refactor).

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	tsx@​4.20.5
	@​octokit/​rest@​20.1.2
	@​actions/​core@​1.11.1

View full report

[charliecreates]

The port standardization looks consistent, but scripts/dev-local.sh has several reliability/diagnostics problems: the port probe may miss collisions due to interface/IPv6 differences, Docker/Supabase readiness checks are brittle (especially greping supabase status), and migration failures are silently ignored. apps/api/src/main.ts also duplicates the port expression, which should be single-sourced in the boot path. Addressing these will make the “one command” local bootstrap significantly more deterministic and debuggable.

Summary of changes

Summary

This PR standardizes local development port assignments across the monorepo and adds a convenience bootstrap script.

Port standardization to 826x

• Updated default local ports in env/examples and docs:
  • API: PORT=8261 in apps/api/.env.example
  • Web: http://localhost:8260 in apps/web/.env.example (NEXTAUTH_URL) and docs
• Updated Next.js dev scripts to bind to explicit ports:
  • apps/web/package.json: next dev -p 8260
  • showcase/package.json: next dev -p 8262
  • docs/package.json: next dev --turbo -p 8263
• Updated web URL fallbacks to use localhost:8260:
  • apps/web/app/robots.ts, apps/web/app/sitemap.ts, apps/web/lib/config.tsx
• Updated tests that assert localhost URL defaults to match the new port:
  • apps/web/lib/urlSecurity.test.ts, apps/web/lib/utils.test.ts

Supabase redirect allowlist alignment

• Updated supabase/config.toml auth URLs to match the new local web port (8260) and added a “keep in sync” comment.

Local dev bootstrap

• Added scripts/dev-local.sh to:
  • Fail fast if ports 8260–8263 are already occupied (via an inline Node node:net bind probe)
  • Start Postgres via Docker Compose
  • Start Supabase via npx --yes supabase ...
  • Run DB migrations
  • Start all dev servers via the new root script dev:cloud:full

Root scripts

• Added dev:cloud:full, dev:local, and dev:docs scripts in the root package.json for streamlined local workflows.

[charliecreates]

Main concern is the new scripts/dev-local.sh reliability/diagnostics: the Docker readiness check is brittle, migration failures are silently ignored, and the port probe can miss collisions due to interface/IPv6 differences. Also, apps/api/src/main.ts duplicates the port expression in a central boot path, which is easy to single-source. Addressing these will make the “one command” local bootstrap more deterministic and significantly easier to troubleshoot.

Summary of changes

Summary

This PR standardizes local development ports across the monorepo and adds a local bootstrap script.

Port standardization to 826x

• API default port updated to 8261 in apps/api/.env.example and apps/api/src/main.ts.
• Web default URLs updated to 8260 across:
  • apps/web/.env.example (NEXTAUTH_URL, NEXT_PUBLIC_TAMBO_API_URL)
  • apps/web/README.md
  • Next metadata routes: apps/web/app/robots.ts, apps/web/app/sitemap.ts
  • apps/web/lib/config.tsx and related tests.
• Next.js dev scripts now bind explicitly:
  • apps/web/package.json: next dev -p 8260
  • showcase/package.json: next dev -p 8262
  • docs/package.json: next dev --turbo -p 8263

Supabase redirect allowlist alignment

• supabase/config.toml auth redirect URLs updated to http://localhost:8260 / https://127.0.0.1:8260 and annotated with a “keep in sync” comment.

Local bootstrap script

• Added scripts/dev-local.sh to:
  • Fail fast if ports 8260–8263 are in use (inline Node node:net probe)
  • Start Postgres via Docker Compose
  • Start Supabase via npx --yes supabase ... and check status via JSON
  • Run DB migrations
  • Start all dev servers via root dev:cloud:full.

Root scripts

• Added dev:cloud:full, dev:local, and dev:docs to the root package.json.