SkillAgentSearch skills...

gen-env

Creates, updates, or reviews a project's gen-env command for running multiple isolated instances on localhost. Handles instance identity, port allocation, data isolation, browser state separation, and cleanup.

Install / Use

npx skills add aiskillstore/marketplace --skill gen-env

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Category

Operations

Supported Platforms

Universal

Our assessment of gen-env

gen-env scores 90/100 on our quality scale, 338th of 760 Operations skills we index (top 45%).

Its SKILL.md is 7.5 KB long, well organised into 39 sections with 16 code examples: a thorough specification that gives an agent plenty to work with.

It has 428 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
11/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so gen-env is actively maintained.
  • Our last check on 2026-10-30 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

gen-env compared with similar skills

All 4 of these similar skills score higher than gen-env; compare them before choosing.

SkillScoreStarsUpdatedFormat
gen-env (this skill)by aiskillstore9042855d agoSKILL.md
algorithmic-artby anthropics100177.9k57d agoSKILL.md
pptxby anthropics100177.9k57d agoSKILL.md
prospectingby coreyhaines3110060.1k7d agoSKILL.md
ad-creativeby coreyhaines3110060.1k7d agoSKILL.md

Frequently asked questions

How do I install gen-env?
Run npx skills add aiskillstore/marketplace --skill gen-env. The install tabs above show the steps for each supported agent.
Which AI agents does gen-env work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is gen-env safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is gen-env still maintained?
The repository was last updated about 2 months ago, so gen-env is actively maintained.

name: gen-env description: Creates, updates, or reviews a project's gen-env command for running multiple isolated instances on localhost. Handles instance identity, port allocation, data isolation, browser state separation, and cleanup.

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:

  1. Does it create instance identity? (not just ports)
  2. Does it set COMPOSE_PROJECT_NAME? (controls Docker naming)
  3. Does it generate a browser-safe host? (*.localhost)
  4. Are URLs derived with correct host? (not hardcoded localhost)
  5. Is cleanup surgical? (can remove one instance without affecting others)
  6. Does the lockfile store the name? (for consistency across runs)
  7. 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)

Related Skills

View on GitHub
GitHub Stars428
CategoryOperations
Updated1mo ago
Forks45

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium