gen-env Skill

Generate or review a gen-env command that enables running multiple isolated instances of a project on localhost simultaneously (e.g., multiple worktrees, feature branches, or versions).

The Problem

Without isolation, multiple instances of the same project:

• Fight for hardcoded ports (3000, 5432, 8080)

• Share Docker volumes → data corruption

• Share browser cookies/localStorage → auth confusion

• Have ambiguous container names → can't tell which is which

• Risk catastrophic cleanup → docker down -v nukes everything

The Solution: Instance Identity

Everything flows from a workspace name:

name = "feature-x" ↓ ┌─────────────────────────────────────────────────────┐ │ COMPOSE_PROJECT_NAME = localnet-feature-x │ │ DOCKER_NETWORK = localnet-feature-x │ │ VOLUME_PREFIX = localnet-feature-x │ │ CONTAINER_PREFIX = localnet-feature-x- │ │ TILT_HOST = feature-x.localhost │ │ Ports = dynamically allocated │ │ URLs = derived from host + ports │ └─────────────────────────────────────────────────────┘

Isolation Dimensions

1. Port Isolation

Each instance gets unique ports from ephemeral range (49152-65535).

2. Data Isolation

Docker Compose project name controls volume naming:

• Instance A: localnet-main_postgres_data

• Instance B: localnet-feature-x_postgres_data

No cross-contamination. Independent databases.

3. Network Isolation

Separate Docker networks per instance. Containers reference each other by service name without collision.

4. Browser State Isolation

Critical: Different ports on localhost still share cookies!

http://localhost:3000 ─┐ ├─ SAME cookies, localStorage http://localhost:3001 ─┘

Solution: subdomain isolation via *.localhost :

http://main.localhost:3000 ─ separate cookies http://feature-x.localhost:3001 ─ separate cookies

Chrome/Edge treat *.localhost as 127.0.0.1 automatically. No /etc/hosts needed.

5. Auth Isolation

Each instance can have its own auth realm/audience, preventing token confusion.

6. Resource Naming

Clear prefixes on containers, volumes, Tilt resources, logs → know exactly which instance you're looking at.

Implementation Checklist

When creating or reviewing gen-env:

Identity & Naming:

• Requires --name <workspace> argument

• Validates name (alphanumeric + dashes, max 63 chars for DNS)

• Generates COMPOSE_PROJECT_NAME from name

• Generates DOCKER_NETWORK , VOLUME_PREFIX , CONTAINER_PREFIX

• Generates *_HOST for browser isolation (name.localhost )

Port Allocation:

• Allocates from ephemeral range (49152-65535)

• Checks port availability before assignment

• Uses short timeout (100ms) for CI compatibility

• Handles IPv6-disabled environments gracefully

Persistence:

• Lockfile stores name + ports (.gen-env.lock )

• Reuses ports when lockfile exists and name matches

• --force regenerates all

• --clean removes generated files

Output:

• Generates .localnet.env (or project-specific name)

• Clear header with generation timestamp

• All derived URLs use correct host + port

Integration:

• Script added to PATH via .envrc

• Generated env sourced by .envrc

• Works with Docker Compose (--env-file )

• Works with Tilt (Starlark reads env file)

Generated Environment Structure

.localnet.env - generated by gen-env

Instance: feature-x

Generated: 2024-01-15T10:30:00Z

=== Instance Identity ===

WORKSPACE_NAME=feature-x COMPOSE_NAME=localnet-feature-x COMPOSE_PROJECT_NAME=localnet-feature-x DOCKER_NETWORK=localnet-feature-x VOLUME_PREFIX=localnet-feature-x CONTAINER_PREFIX=localnet-feature-x-

=== Host (for browser isolation) ===

APP_HOST=feature-x.localhost TILT_HOST=feature-x.localhost

=== Allocated Ports ===

POSTGRES_PORT=51234 REDIS_PORT=51235 API_PORT=51236 WEB_PORT=51237

... more ports

=== Derived URLs ===

DATABASE_URL=postgres://user:pass@localhost:51234/dev WEB_URL=http://feature-x.localhost:51237 API_URL=http://feature-x.localhost:51236

direnv Integration

.envrc

PATH_add bin # or scripts

dotenv_if_exists .localnet.env

Reference Implementation (TypeScript/Bun)

See @IMPLEMENTATION.md for full implementation.

Key types:

interface InstanceConfig { name: string; // Workspace identity composeName: string; // Docker Compose project name dockerNetwork: string; // Docker network name volumePrefix: string; // Docker volume prefix containerPrefix: string; // Container name prefix host: string; // Browser hostname (name.localhost) ports: Record<string, number>; // Allocated ports urls: Record<string, string>; // Derived URLs }

interface LockfileData { version: 1; generatedAt: string; instance: InstanceConfig; }

Cleanup Patterns

Surgical cleanup per instance:

Clean only feature-x (containers + volumes + networks)

docker compose -p localnet-feature-x down -v

Or via gen-env

gen-env --clean # removes .localnet.env and .gen-env.lock

List all localnet instances

docker ps -a --filter "name=localnet-" --format "table {{.Names}}\t{{.Status}}"

Nuclear option (all instances) - DANGEROUS

docker ps -a --filter "name=localnet-" -q | xargs docker rm -f docker volume ls --filter "name=localnet-" -q | xargs docker volume rm

Common Patterns

Pattern 1: Worktree-Based Naming

Derive name from git worktree directory

WORKTREE_NAME=$(basename "$(git rev-parse --show-toplevel)") gen-env --name "$WORKTREE_NAME"

Pattern 2: Branch-Based Naming

Derive name from branch

BRANCH=$(git branch --show-current | tr '/' '-') gen-env --name "$BRANCH"

Pattern 3: Explicit Naming

User specifies (recommended for clarity)

gen-env --name bb-dev gen-env --name testing-v2

Review Checklist

When reviewing an existing gen-env:

• Does it create instance identity? (not just ports)

• Does it set COMPOSE_PROJECT_NAME? (controls Docker naming)

• Does it generate a browser-safe host? (*.localhost )

• Are URLs derived with correct host? (not hardcoded localhost )

• Is cleanup surgical? (can remove one instance without affecting others)

• Does the lockfile store the name? (for consistency across runs)

• Does it validate name conflicts? (warn if lockfile has different name)

Anti-Patterns

❌ Hardcoded localhost in URLs

WEB_URL=http://localhost:${WEB_PORT} # BAD: shares cookies

✅ Use instance host

WEB_URL=http://${APP_HOST}:${WEB_PORT} # GOOD: isolated cookies

❌ No COMPOSE_PROJECT_NAME

BAD: uses directory name, may conflict

docker compose up

✅ Explicit project name

COMPOSE_PROJECT_NAME=localnet-feature-x docker compose up # Uses project name for all resources

❌ Shared cleanup

docker compose down -v # BAD: which instance?

✅ Instance-specific cleanup

docker compose -p localnet-feature-x down -v # GOOD: explicit

References

• @IMPLEMENTATION.md - Full TypeScript implementation

• @ADVANCED_PATTERNS.md - Complex scenarios (monorepos, CI, Tilt integration)