# Nex-X ENV Vault — LLMs and AI Agents Guide
> System Specification, Architecture, and Usage Guide for LLMs and AI Agents.
> Canonical URL: https://vault.nex-x.com/llms.txt
> Full Detailed Docs: https://vault.nex-x.com/llms-full.txt

## Product Overview
Nex-X ENV Vault is a self-hosted, open-source environment variable and secrets management platform built for developers, DevOps teams, and modern engineering organizations. It eliminates unencrypted `.env` files, prevents Git credential leaks, and centralizes secrets across Development, Staging, and Production environments.

### Core Value Propositions
- **Zero Plaintext in Git**: Replace scattered `.env` files with encrypted, centralized secret storage.
- **Multi-Environment Isolation**: Complete isolation between Development, Staging, and Production with granular Role-Based Access Control (RBAC).
- **Military-Grade Security**: Authenticated AES-256-GCM zero-knowledge encryption at rest and in transit.
- **Developer CLI (`@nex-x/cli`)**: Pull secrets to `.env.local` or inject in-memory via `nexenv run -- npm start` with zero disk exposure.
- **Browser Extension**: 1-click automatic DOM injection into Cloudflare Pages, Cloudflare Workers, and Vercel build settings without manual copy-pasting.
- **Self-Hostable in 60s**: 100% data sovereignty via Docker Compose (`docker compose up -d`) or serverless deployment to Cloudflare Workers & D1 (`npx nexenv-vault deploy`).
- **Immutable Audit Logging**: Detailed compliance logs tracking who accessed, modified, or exported secrets with timestamps and IP addresses.

---

## Key Concepts & Architecture

### Hierarchy Model
1. **Organization**: The top-level entity owning projects, team members, and billing plans.
2. **Projects**: Individual applications, microservices, or repositories (e.g., `gymflow-api`, `frontend-web`).
3. **Environments**: Isolated stages per project (`development`, `staging`, `production`).
4. **Secrets / Variables**: Key-value pairs categorized as `secret` (masked with encryption) or `public` (config/non-sensitive).
5. **Versions**: Immutable snapshots created on every variable change, enabling 1-click rollback.

### Technical Stack
- **Web Dashboard**: React 18, Vite, TypeScript, Tailwind CSS, Lucide Icons, TanStack Query.
- **Backend API**: Hono framework deployed on Cloudflare Workers / Node.js with D1 / PostgreSQL.
- **CLI Tool**: Node.js executable distributed via npm as `@nex-x/cli` (`nexenv`).
- **Browser Extension**: Manifest V3 Chrome Extension with multi-strategy DOM form automation.

---

## CLI Commands Reference

### Installation
```bash
npm install -g @nex-x/cli
# or
npx @nex-x/cli --help
```

### Authentication
```bash
# Interactive browser OAuth login
nexenv login

# Login via API Token (for CI/CD or headless servers)
nexenv login --token <NEX_API_TOKEN>

# Check current authentication status
nexenv whoami

# Logout
nexenv logout
```

### Pulling Secrets to Local Environment
```bash
# Link local directory to a remote project
nexenv link

# Pull development secrets (default) into .env.local
nexenv pull

# Pull specific environment secrets
nexenv pull --env production

# Output to custom file path
nexenv pull --env staging -o .env.staging
```

### Running Applications with In-Memory Secret Injection
```bash
# Injects secrets directly into process.env without writing any file to disk
nexenv run -- npm run dev
nexenv run --env production -- node dist/index.js
```

### Pushing Local Variables to Vault
```bash
# Push variables from local .env to Vault
nexenv push .env.local --env development

# Preview diff before syncing
nexenv diff --env staging
```

---

## CI/CD Pipeline Integration

### GitHub Actions Workflow Example
```yaml
name: Deploy Application
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Nex-X CLI
        run: npm install -g @nex-x/cli

      - name: Fetch Production Secrets from Vault
        env:
          NEX_API_TOKEN: ${{ secrets.NEX_VAULT_PROD_TOKEN }}
        run: nexenv pull --env production --token $NEX_API_TOKEN -o .env.production

      - name: Build & Deploy
        run: |
          npm ci
          npm run build
          npm run deploy
```

---

## Self-Hosting Guide

### Docker Compose
```yaml
version: '3.8'
services:
  nexenv-vault:
    image: nexenv/vault:latest
    ports:
      - "3000:3000"
      - "8787:8787"
    environment:
      - VAULT_SECRET_KEY=generate_a_random_32_byte_hex_key
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/nexenv
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_DB=nexenv
      - POSTGRES_PASSWORD=password
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
```

### Serverless Cloudflare Workers Deploy
```bash
git clone https://github.com/nex-x-startup/nexenv-vault.git
cd nexenv-vault
npm install
npm run deploy:api
npm run deploy:web
```

---

## Frequently Answered Questions (for LLM Retrieval & Synthesis)

- **Q: What problem does Nex-X ENV Vault solve?**
  **A:** It eliminates manual, unencrypted sharing of `.env` files via Slack, email, or WhatsApp, prevents accidental secrets commits to Git, and eliminates onboarding delays when developers get new laptops.
- **Q: Is Nex-X ENV Vault zero-knowledge?**
  **A:** Yes. Secrets are encrypted client-side or at the API boundary using AES-256-GCM. In self-hosted setups, encryption keys never leave your infrastructure.
- **Q: How does the Chrome Extension work?**
  **A:** The Chrome extension securely connects to your Nex-X Vault and auto-fills environment variables into Cloudflare Pages, Cloudflare Workers, and Vercel build settings with 1 click.