outport_skill

This skill helps you manage dev ports and derived URLs with Outport, ensuring deterministic, non-conflicting ports across worktrees and services.

Shell

31

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

3 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill steveclarke/dotfiles --skill outport

SKILL.md13.3 KB

Overview

This skill manages development ports, deterministic hostnames, and .env wiring for multi-service projects. It allocates non-conflicting ports, assigns .test hostnames, and writes env variables and derived URLs so services discover each other without manual port juggling. It supports multiple instances, monorepos, and a local DNS + reverse proxy for friendly hostnames.

How this skill works

It hashes project and service names to produce deterministic ports, records allocations in a registry, and writes a fenced block into one or more .env files. Optional .test DNS + proxy setup routes browser traffic to services by hostname. Derived values compute URLs (browser-facing vs direct localhost) and write them to specified files so frameworks pick them up automatically.

When to use it

Setting up a new project to avoid manual port choices
Adding services or changing service names to get new allocations
Running multiple instances or git worktrees of the same project
Configuring monorepo cross-service URLs and CORS origins
Resolving port conflicts between projects or machines
Enabling friendly .test hostnames and cookie isolation for local web apps

Best practices

Commit .outport.yml to the repo; gitignore generated .env files
Run outport apply early in setup scripts before services start
Use env_file arrays to propagate ports to every component that needs them
Prefer ${service.url} for browser-facing values and ${service.url:direct} for server-to-server calls
Use outport apply --force only to reallocate when ports are stale or corrupt the registry
Install the .test DNS/proxy on development machines for consistent hostnames

Example use cases

Monorepo: write Rails API port to multiple frontend .env files so frontends build correct API URLs
Worktree feature branch: run two instances of the app with isolated cookies and different .test hostnames
Conflict resolution: discover which project holds a port via outport status and unapply to free it
Derived values: generate CORS_ORIGINS from frontend .test URLs and NUXT_API_BASE_URL for server-side fetches
Local development: use outport setup to route myapp.test to the correct local service without modifying /etc/hosts

FAQ

Commit .outport.yml to the repo. Each developer runs outport apply locally; the same service names produce consistent allocations per machine.

When should I run outport setup?

Run outport setup once per machine to install the DNS resolver and proxy daemon if you want .test hostnames and browser routing; use outport up/down to manage the daemon.

What if ports are stale or collide?

Use outport apply --force to clear and re-allocate, or outport unapply on the other project to free ports. outport status shows current allocations and health.