Env Manager

Set up and manage dev environments. Python/Node/Docker/Go/Rust project scaffolding, port tracking, service management, and cleanup. Zero external dependencies.

Stop setting up dev environments by hand. Start scaffolding them in seconds.

The Problem

Every new project needs a dev environment: Python venv, Node project, Docker setup, Go module, or Rust crate. That's boilerplate you don't want to type every time.

Env Manager automates environment scaffolding, port tracking, and service management.

Quick Start

Create a Python environment

bash

node skills/env-manager/env-manager.js --setup python my-project

Creates a virtualenv with activation instructions.

Create a Node project

bash

node skills/env-manager/env-manager.js --setup node my-app

Creates package.json, index.js, and .gitignore.

Create a Docker project

bash

node skills/env-manager/env-manager.js --setup docker my-service

Creates Dockerfile and docker-compose.yml.

Create a Go project

bash

node skills/env-manager/env-manager.js --setup go my-api

Initializes Go module with main.go.

Create a Rust project

bash

node skills/env-manager/env-manager.js --setup rust my-cli

Creates Cargo.toml and src/main.rs.

List managed ports

bash

node skills/env-manager/env-manager.js --ports

Find free ports

bash

node skills/env-manager/env-manager.js --ports --free

List managed services

bash

node skills/env-manager/env-manager.js --services

Check service health

bash

node skills/env-manager/env-manager.js --services --status my-service

Start/stop a service

bash

node skills/env-manager/env-manager.js --services --start my-service
node skills/env-manager/env-manager.js --services --stop my-service

Clean up inactive environments

bash

node skills/env-manager/env-manager.js --cleanup

Status overview

bash

node skills/env-manager/env-manager.js --status

Features

Multi-Language Scaffolding

• Python — venv with python3, pip detection
• Node — package.json with dev scripts, .gitignore
• Docker — Dockerfile + docker-compose.yml
• Go — go.mod + main.go
• Rust — Cargo.toml + src/main.rs

Port Tracking

• Tracks which ports are managed by which services
• Finds free ports in range 3000-9000 (multiples of 10)
• Shows running/stopped status

Service Management

• List, start, stop, and health check services
• Port-based health detection via lsof
• Persistent service state in JSON

Environment Cleanup

• Identifies inactive environments
• Reports what would be cleaned
• No destructive action by default

Environment Types Tracking

• Counts environments by type
• Shows version info for each environment
• Persistent across restarts

Configuration

Data files stored in: memory/environments/

• environments.json — Environment definitions
• ports.json — Port tracking
• services.json — Service management

Environments created in: environments/

Override data directory:

bash

--dir /path/to/data

Agent Protocol

When setting up new projects:

1. Choose the right type — --setup <python|node|docker|go|rust>
2. Name explicitly — --setup node my-app (auto-names are hard to find)
3. Check ports — --ports --free before starting new services
4. Track services — Register new services in services.json
5. Clean up — --cleanup periodically to remove stale environments

Heartbeat Integration

Add to your HEARTBEAT.md:

markdown

### 🛠️ Environment Check

- Run `node skills/env-manager/env-manager.js --services --status` to check service health
- Run `node skills/env-manager/env-manager.js --ports` to check port usage

Limitations

• Service start/stop is state tracking only (no actual process management)
• Port detection uses lsof (Linux only)
• Environment creation depends on tools being installed (python3, node, docker, go, rustc)
• No automatic dependency installation

Comparison

Approach	Scaffolding	Port Tracking	Service Mgmt
Manual	❌	❌	❌
Docker Compose	⚠️	❌	⚠️
Env Manager	✅	✅	✅

Env Manager gives you multi-language scaffolding + port tracking + service management in one tool.

Security

Command Allowlist

Only pre-approved binaries can be executed: python3, node, npm, docker, go, rustc, pip3, lsof

Shell Escaping

All user-provided values (environment names, paths, port numbers) are shell-escaped to prevent injection.

Path Validation

Before executing any command, the skill validates that the binary exists on the system.

Dry-Run Mode

Set ENV_DRY_RUN=1 to see what commands would run without executing them. Useful for reviewing actions before they happen.

Design Principles

1. Zero setup — Works immediately, no config needed
2. No dependencies — Pure Node.js fs/child_process, no npm packages
3. Multi-language — Python, Node, Docker, Go, Rust in one tool
4. Persistent — Environments, ports, and services tracked in JSON
5. Safe — Dry-run cleanup, no destructive action by default