envcp

Secure Environment Variable Management for AI agent

EnvCP lets you safely use AI agent without exposing your secrets.
Your API keys and environment variables stay encrypted on your machine — AI only references them by name.

Installation

npm

npm install -g @fentz26/envcp

pip (Python)

pip install envcp

Requires Node.js 18+ to be installed.

curl

curl -fsSL https://envcp.fentz.dev/install.sh | bash

Use without installing

npx @fentz26/envcp init

Quick Start

# 1. Initialize in your project
envcp init

# 2. Add your secrets
envcp add API_KEY --value "your-secret-key"
envcp add DATABASE_URL --value "postgres://..."

# 3. Start the server (auto-detects client type)
envcp serve --mode auto --port 3456

Basic CLI Commands

# Variable Management
envcp add <name> [options]    # Add a variable
envcp list [--show-values]    # List variables
envcp get <name>              # Get a variable
envcp remove <name>           # Remove a variable

# Session Management
envcp unlock                  # Unlock with password
envcp lock                    # Lock immediately
envcp status                  # Check session status

# Sync and Export
envcp sync                    # Sync to .env file
envcp export [--format env|json|yaml]

Why EnvCP?

• Local-only storage — Your secrets never leave your machine
• Encrypted at rest — AES-256-GCM with Argon2id key derivation (64 MB memory, 3 passes)
• Reference-based access — AI references variables by name, never sees the actual values
• Automatic .env injection — Values can be automatically injected into your .env files
• AI Access Control — Block AI from proactively listing or checking your secrets
• Universal Compatibility — Works with any AI tool via MCP, OpenAI, Gemini, or REST protocols

Integration Guides

Claude Desktop / Cursor / Cline (MCP)

Add to your MCP config file:

{
  "mcpServers": {
    "envcp": {
      "command": "npx",
      "args": ["@fentz26/envcp", "serve", "--mode", "mcp"]
    }
  }
}

ChatGPT / OpenAI API

envcp serve --mode openai --port 3456 --api-key your-secret-key

import openai

client = openai.OpenAI(
    base_url="http://localhost:3456/v1",
    api_key="your-secret-key"
)

# Call a function
result = client.post("/functions/call", json={
    "name": "envcp_get",
    "arguments": {"name": "API_KEY"}
})

Gemini / Google AI

envcp serve --mode gemini --port 3456 --api-key your-secret-key

import requests

# Get available tools
tools = requests.get(
    "http://localhost:3456/v1/tools",
    headers={"X-Goog-Api-Key": "your-secret-key"}
).json()

# Call a function
result = requests.post(
    "http://localhost:3456/v1/functions/call",
    headers={"X-Goog-Api-Key": "your-secret-key"},
    json={"name": "envcp_get", "args": {"name": "API_KEY"}}
).json()

Local LLMs (Ollama, LM Studio)

# OpenAI-compatible (works with most local LLM tools)
envcp serve --mode openai --port 3456

# Or universal REST
envcp serve --mode rest --port 3456

Configure your LLM tool to use http://localhost:3456 as the tool server.

REST API (Universal)

envcp serve --mode rest --port 3456 --api-key your-secret-key

Endpoints:

GET    /api/health              - Health check
GET    /api/variables           - List variables
GET    /api/variables/:name     - Get variable
POST   /api/variables           - Create variable
PUT    /api/variables/:name     - Update variable
DELETE /api/variables/:name     - Delete variable
POST   /api/sync                - Sync to .env
POST   /api/run                 - Run command with env vars
GET    /api/tools               - List available tools
POST   /api/tools/:name         - Call tool by name

# List variables
curl -H "X-API-Key: your-secret-key" http://localhost:3456/api/variables

# Get a variable
curl -H "X-API-Key: your-secret-key" http://localhost:3456/api/variables/API_KEY

# Create a variable
curl -X POST -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "NEW_VAR", "value": "secret123"}' \
  http://localhost:3456/api/variables

Server Modes

envcp serve [options]
  --mode, -m      Server mode: mcp, rest, openai, gemini, all, auto
  --port          HTTP port (default: 3456)
  --host          HTTP host (default: 127.0.0.1)
  --api-key, -k   API key for authentication
  --password, -p  Encryption password

Platform Compatibility

Available Tools

All protocols expose the same tools:

Configuration (envcp.yaml)

version: "1.0"
project: my-project

storage:
  path: .envcp/store.enc
  encrypted: true
  algorithm: aes-256-gcm

session:
  enabled: true
  timeout: 1800  # 30 minutes

access:
  allow_ai_read: true
  allow_ai_write: false
  allow_ai_active_check: false  # Prevent AI from proactively listing
  require_confirmation: true
  blacklist:
    - "*_SECRET"
    - "*_PRIVATE"
    - "ADMIN_*"

password:
  min_length: 1  # No requirements by default
  require_uppercase: false
  require_lowercase: false
  require_numbers: false
  require_special: false

sync:
  enabled: true
  target: .env
  exclude:
    - "*_PRIVATE"
    - "*_SECRET"

AI Access Control

Disable Active Checking

Prevent AI from proactively listing your variables:

access:
  allow_ai_active_check: false

Blacklist Patterns

Block AI from accessing sensitive variables:

access:
  blacklist:
    - "*_SECRET"
    - "*_PRIVATE"
    - "ADMIN_*"
    - "ROOT_*"

Security

Encryption Details

• Cipher: AES-256-GCM (authenticated encryption)
• Key Derivation: Argon2id (64 MB memory, 3 passes, parallelism 1)
• Salt: 16 bytes per encryption (random)
• IV: 16 bytes per encryption (random)
• Auth Tag: 16 bytes for integrity verification
• Legacy: existing v1 stores (PBKDF2) are automatically read and re-encrypted on next write

MCP (stdio) Authentication

The MCP server runs over stdio — it is only accessible to processes on your local machine that spawn it. No network port is opened in MCP mode; security is enforced by OS process isolation.

API Authentication

When using HTTP modes, always set an API key:

envcp serve --mode rest --api-key your-secret-key

Clients must include the key in requests:

X-API-Key: your-secret-key
# or
Authorization: Bearer your-secret-key

Best Practices

1. Never commit .envcp/ — Add to .gitignore
2. Use API keys for HTTP modes — Protect your server endpoints
3. Disable allow_ai_active_check — Prevent AI from probing for variables
4. Use blacklist patterns — Block sensitive variable patterns
5. Use auto mode for HTTP — Let EnvCP detect the client type
6. Review access logs — Check .envcp/logs/ regularly

License

SAL v1.0 — See LICENSE file for details.

Support

• Email: contact@fentz.dev
• GitHub Issues: https://github.com/fentz26/EnvCP/issues
• Documentation: https://envcp.fentz.dev/docs