Agent skill

portless

Named .localhost URLs for local development with portless. Eliminates port collisions, enables stable URLs for agents, integrates with emulate for API emulation aliases and git worktrees for branch-named subdomains. Use when setting up local dev environments, configuring agent-accessible URLs, or running multi-service dev setups. Do NOT use for production deployments, CI environments (set PORTLESS=0), or DNS/hosting configuration.

View SKILL.md on GitHub Repository
Stars 143
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/yonatangross/orchestkit/tree/main/plugins/ork/skills/portless

SKILL.md

Portless Integration

Named .localhost URLs for local development. Replaces localhost:3000 with https://myapp.localhost.

Full CLI reference: Load Read("${CLAUDE_SKILL_DIR}/references/upstream.md") for complete command docs.

When to Use

  • Starting a dev server that agents or browser tests will target
  • Running multiple services locally (API + frontend + docs)
  • Working in git worktrees (branch-named subdomains)
  • Local OAuth flows (stable callback URLs)
  • Connecting emulate API mocks to named URLs

Quick Start

bash
# Instead of: npm run dev (random port)
portless run npm run dev
# → https://myapp.localhost (stable, named, HTTPS)

# Multi-service
portless run --name api npm run dev:api
portless run --name web npm run dev:web
# → https://api.localhost, https://web.localhost

Framework-Specific Setup

Load Read("${CLAUDE_SKILL_DIR}/references/framework-integration.md") for full framework recipes.

Most frameworks (Next.js, Vite, Express) work with portless run <cmd>. Some need explicit flags:

Framework Auto-detected? Extra flags needed
Next.js Yes None
Vite / Astro Yes None
Express / Fastify / Hono Yes None (reads PORT env var)
Ruby on Rails Yes None
FastAPI / uvicorn No --port $PORT --host $HOST
Django No $HOST:$PORT positional arg

Why .localhost?

Feature .localhost (RFC 6761) 127.0.0.1:PORT /etc/hosts hack
No /etc/hosts editing Yes Yes No
HTTPS with valid cert Yes No Manual
Wildcard subdomains Yes No No
Works in all browsers Yes Yes Varies
Cookie isolation per service Yes No Yes
No port conflicts Yes No Yes

Key Environment Variables

When portless runs your command, it injects:

Variable Value Use in agents
PORT Assigned ephemeral port (4000-4999) Internal only
HOST 127.0.0.1 Internal only
PORTLESS_URL https://myapp.localhost Use this in agent prompts

OrchestKit Integration Patterns

1. Agent-Accessible Dev Server

bash
# Start with portless, then agents can target PORTLESS_URL
portless run npm run dev

# In ork:expect or agent-browser:
agent-browser open $PORTLESS_URL

2. Emulate + Portless (Named API Mocks)

bash
# Register emulate ports as named aliases
portless alias github-api 4001
portless alias vercel-api 4000
portless alias google-api 4002

# Now agents can target:
#   https://github-api.localhost — GitHub emulator
#   https://vercel-api.localhost — Vercel emulator

3. Git Worktree Dev

bash
# In worktree for feature/auth-flow:
portless run npm run dev
# → https://auth-flow.myapp.localhost (auto branch prefix)

4. Bypass in CI

bash
# Disable portless in CI — direct port access
PORTLESS=0 npm run dev

Anti-Patterns

Don't Do Instead
Hardcode localhost:3000 in tests Use PORTLESS_URL or process.env.PORTLESS_URL
Run portless in CI Set PORTLESS=0 in CI environments
Use numeric ports in AGENTS.md Document the portless URL

References

File Content
references/upstream.md Full portless CLI reference (synced from Vercel)
references/upstream-oauth.md OAuth callback patterns with stable URLs
references/framework-integration.md Framework recipes (FastAPI, Django, Docker, gotchas)
checklists/new-project-setup.md Step-by-step: add portless to a new project

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

yonatangross/orchestkit

expect

Diff-aware AI browser testing — analyzes git changes, generates targeted test plans, and executes them via agent-browser. Reads git diff to determine what changed, maps changes to affected pages via route map, generates a test plan scoped to the diff, and runs it with pass/fail reporting. Use when testing UI changes, verifying PRs before merge, running regression checks on changed components, or validating that recent code changes don't break the user-facing experience.

143 15
Explore
yonatangross/orchestkit

github-operations

GitHub CLI operations for issues, PRs, milestones, and Projects v2. Covers gh commands, REST API patterns, and automation scripts. Use when managing GitHub issues, PRs, milestones, or Projects with gh.

143 15
Explore
yonatangross/orchestkit

chain-patterns

Chain patterns for CC 2.1.71 pipelines — MCP detection, handoff files, checkpoint-resume, worktree agents, CronCreate monitoring. Use when building multi-phase pipeline skills. Loaded via skills: field by pipeline skills (fix-issue, implement, brainstorm, verify). Not user-invocable.

143 15
Explore
yonatangross/orchestkit

storybook-mcp-integration

Storybook MCP server integration for component-aware AI development. Covers 6 tools across 3 toolsets (dev, docs, testing): component discovery via list-all-documentation/get-documentation, story previews via preview-stories, and automated testing via run-story-tests. Use when generating components that should reuse existing Storybook components, running component tests via MCP, or previewing stories in chat.

143 15
Explore
yonatangross/orchestkit

component-search

Search 21st.dev component registry for production-ready React components. Finds components by natural language description, filters by framework and style system, returns ranked results with install instructions. Use when looking for UI components, finding alternatives to existing components, or sourcing design system building blocks.

143 15
Explore
yonatangross/orchestkit

ai-ui-generation

AI-assisted UI generation patterns for json-render, v0, Bolt, and Cursor workflows. Covers prompt engineering for component generation, review checklists for AI-generated code, design token injection, refactoring for design system conformance, and CI gates for quality assurance. Use when generating UI components with AI tools, rendering multi-surface MCP visual output, reviewing AI-generated code, or integrating AI output into design systems.

143 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results