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-envInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| gen-env (this skill)by aiskillstore | 90 | 428 | 55d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 57d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 57d ago | SKILL.md |
| prospectingby coreyhaines31 | 100 | 60.1k | 7d ago | SKILL.md |
| ad-creativeby coreyhaines31 | 100 | 60.1k | 7d ago | SKILL.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.
Skill content
View source on GitHubname: 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 -vnukes 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_NAMEfrom name - [ ] Generates
DOCKER_NETWORK,VOLUME_PREFIX,CONTAINER_PREFIX - [ ] Generates
*_HOSTfor 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
- [ ]
--forceregenerates all - [ ]
--cleanremoves 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)
Related Skills
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
prospecting
60.1kWhen the user wants to find and qualify prospects for outbound, or asks who to target first, which signal to prioritize, or where to spot buyers with the problem: buying signals, enrichment, verification, account research.
ad-creative
60.1kWhen the user wants to write or judge ad creative, or asks which ad, hook, or angle to run or kill: headlines, primary text, and variations for Google, Meta, LinkedIn, and TikTok, fresh angles when creative fatigues. Test hypotheses name the metric, comparison, and expected direction.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
