# REP — Runtime Environment Protocol

> An open specification and reference implementation for injecting environment
> variables into browser-hosted applications at container runtime rather than at
> build time. A ~7MB Go gateway classifies REP_* variables into PUBLIC/SENSITIVE/SERVER
> tiers, encrypts the sensitive ones with AES-256-GCM, and injects them into every HTML
> response. A zero-dependency TypeScript SDK reads them — synchronously for public vars.

Every page below is available as plain-text Markdown at the listed URL.
Start with https://rep-protocol.dev/agents.md — a single-page integration playbook written for AI agents.
The complete documentation set as one file: https://rep-protocol.dev/llms-full.txt

## Getting Started

- [Quick Start](https://rep-protocol.dev/quick-start.md): Get runtime environment variables in your frontend app in under 5 minutes. Install the SDK, rename your env vars, and run the gateway. No manifest required.
- [Installation](https://rep-protocol.dev/guides/installation.md): Install @rep-protocol/sdk, framework adapters for React/Vue/Svelte, the CLI tool, and the Go gateway binary. npm packages and Docker image options.
- [Local Development](https://rep-protocol.dev/guides/development.md): Develop locally with REP using default values, mock DOM payloads, or the CLI dev server that wraps the gateway. Works alongside Vite, webpack, and any dev server.

## For AI Agents

- [For AI Agents](https://rep-protocol.dev/agents.md): A single-page, machine-readable playbook for AI coding agents integrating REP. Decision tree, install matrix, copy-paste recipes for SDK, Docker, Kubernetes, and every framework, plus the mistakes that break a REP setup.

## Core Concepts

- [How REP Works](https://rep-protocol.dev/concepts/how-it-works.md): How the REP gateway injects environment variables into HTML at runtime. Proxy and embedded modes, startup sequence, script tag injection, and SDK initialization.
- [Variable Classification](https://rep-protocol.dev/concepts/variable-classification.md): REP's three-tier security model for environment variables. PUBLIC for plaintext, SENSITIVE for AES-256 encrypted, SERVER for gateway-only. Classified by naming convention.
- [Security Model](https://rep-protocol.dev/concepts/security-model.md): REP's security model explained. Threat analysis for XSS, CDN compromise, env var leaks, and more. Trust boundaries, encryption design, and known limitations.
- [Wire Format](https://rep-protocol.dev/concepts/wire-format.md): The REP payload wire format. JSON structure, AES-256-GCM encrypted blob, HKDF key derivation, HMAC-SHA256 integrity tokens, and SRI verification.
- [Hot Reload](https://rep-protocol.dev/concepts/hot-reload.md): Push environment variable changes to every connected browser via SSE. No page reload, no redeployment. File watch, signal, and poll detection modes.

## Framework Guides

- [React](https://rep-protocol.dev/frameworks/react.md): Access runtime environment variables in React with useRep() and useRepSecure() hooks. Synchronous reads, encrypted secrets, and automatic hot reload re-rendering.
- [Vue](https://rep-protocol.dev/frameworks/vue.md): Access runtime environment variables in Vue 3 with useRep() and useRepSecure() composables. Reactive refs with automatic hot reload updates.
- [Svelte](https://rep-protocol.dev/frameworks/svelte.md): Access runtime environment variables in Svelte with repStore() and repSecureStore(). Native readable stores with lazy SSE hot reload subscriptions.
- [Angular](https://rep-protocol.dev/frameworks/angular.md): Access runtime environment variables in Angular with an injectable RepService. Observable support for reactive config updates without page reload.
- [Vanilla JS](https://rep-protocol.dev/frameworks/vanilla.md): Access runtime environment variables in plain JavaScript with ESM imports. No framework, no build tool — works in any browser app that produces HTML.

## Guides

- [Manifest File](https://rep-protocol.dev/guides/manifest.md): Declare environment variables, types, defaults, and validation rules in .rep.yaml. Generate TypeScript types and validate config at gateway startup.
- [Testing](https://rep-protocol.dev/guides/testing.md): Test apps that use REP. Mock payloads for unit tests with Vitest/Jest, Docker Compose for integration tests, and rep lint for scanning built bundles for leaked secrets.
- [Overview](https://rep-protocol.dev/guides/migration/overview.md): Four-phase migration from build-time environment variables to REP runtime injection. Covers infrastructure setup, SDK adoption, build cleanup, and security hardening.
- [From Vite](https://rep-protocol.dev/guides/migration/from-vite.md): Automated codemod to migrate from Vite's import.meta.env.VITE_* to REP runtime environment variables. Transforms all references and adds SDK imports.
- [From Create React App](https://rep-protocol.dev/guides/migration/from-cra.md): Automated codemod to migrate from Create React App's process.env.REACT_APP_* to REP runtime environment variables. Drop build-time env var dependency.
- [From Next.js](https://rep-protocol.dev/guides/migration/from-next.md): Migrate from Next.js NEXT_PUBLIC_* build-time variables to REP runtime environment variables. Handles client-side code, SSR considerations, and automated codemod.

## Deployment

- [Docker — Proxy Mode](https://rep-protocol.dev/deployment/docker-proxy.md): Deploy the REP gateway as a reverse proxy in front of nginx or Caddy. Multi-stage Dockerfile, runtime environment variable injection into HTML responses.
- [Docker — Embedded Mode](https://rep-protocol.dev/deployment/docker-embedded.md): Deploy a frontend app in a minimal FROM scratch Docker container. The REP gateway serves static files directly — no nginx, no Node.js, no shell. Under 10MB total.
- [Kubernetes](https://rep-protocol.dev/deployment/kubernetes.md): Deploy REP in Kubernetes with ConfigMaps for public vars, Secrets for sensitive vars, sidecar patterns, and hot reload via file watch. Includes health probes and Service config.
- [Docker Compose](https://rep-protocol.dev/deployment/docker-compose.md): Run the same frontend Docker image across staging and production with Docker Compose. Different environment variables per service, .env file support, and dev proxy setup.
- [CI/CD Pipeline](https://rep-protocol.dev/deployment/ci-cd.md): Build your frontend Docker image once in CI and promote it across staging and production without rebuilding. GitHub Actions example with manifest validation and bundle scanning.

## Examples

- [Todo App (React)](https://rep-protocol.dev/examples/todo-react.md): Full worked example of a React todo app using REP. useRep() hooks, useRepSecure() for encrypted vars, hot reload, and Docker deployment with FROM scratch containers.
- [Simple HTML (ESM.sh)](https://rep-protocol.dev/examples/simple-html.md): Use REP in a plain HTML file with no bundler or framework. The SDK is loaded via esm.sh and the gateway serves the file in embedded mode with a FROM scratch container.
- [Next.js — Proxy Mode](https://rep-protocol.dev/examples/nextjs-proxy.md): Run the REP gateway as a reverse proxy in front of a Next.js SSR server. Environment variables are injected into every HTML response without touching the Next.js build.
- [Next.js CSR + Kubernetes](https://rep-protocol.dev/examples/nextjs-csr-embedded.md): Export Next.js as a static site, serve it with the REP gateway in embedded mode, and manage feature flags dynamically via a Kubernetes ConfigMap. Includes a hot-reload variant with zero pod restarts.

## Reference

- [SDK API](https://rep-protocol.dev/reference/sdk.md): Complete API reference for @rep-protocol/sdk. Synchronous get() for public vars, async getSecure() for encrypted vars, onChange() for hot reload, verify() for integrity checks.
- [Gateway Flags](https://rep-protocol.dev/reference/gateway-flags.md): All CLI flags and REP_GATEWAY_* environment variables for configuring the gateway. Port, mode, upstream, strict mode, hot reload, logging, CORS, and rate limiting options.
- [Gateway Endpoints](https://rep-protocol.dev/reference/gateway-endpoints.md): REP gateway HTTP endpoints. /rep/health for status checks, /rep/session-key for AES decryption keys with rate limiting, and /rep/changes for SSE hot reload events.
- [Manifest Schema](https://rep-protocol.dev/reference/manifest-schema.md): Complete reference for the .rep.yaml manifest. Variable declarations, supported types (string, url, number, boolean, csv, json, enum), defaults, required flags, and gateway settings.
- [CLI Commands](https://rep-protocol.dev/reference/cli.md): Reference for @rep-protocol/cli commands. Validate manifests, generate TypeScript types from .rep.yaml, scan bundles for leaked secrets, and run a local dev server.
- [React](https://rep-protocol.dev/reference/adapters/react.md): API reference for @rep-protocol/react. useRep() for synchronous public variable access with hot reload re-rendering. useRepSecure() for encrypted variable decryption.
- [Vue](https://rep-protocol.dev/reference/adapters/vue.md): API reference for @rep-protocol/vue. useRep() returns a reactive Ref for public variables. useRepSecure() returns an async Ref for encrypted variable decryption.
- [Svelte](https://rep-protocol.dev/reference/adapters/svelte.md): API reference for @rep-protocol/svelte. repStore() creates a readable store for public variables with SSE hot reload. repSecureStore() for async encrypted variable access.
- [Vite](https://rep-protocol.dev/reference/plugins/vite.md): API reference for the REP Vite plugin. repPlugin() options, dev-mode behavior, the /rep/session-key middleware, and how it differs from the production gateway.
- [Next.js](https://rep-protocol.dev/reference/plugins/next.md): API reference for the REP Next.js plugin. RepScript props, the session-key route handler, and how the plugin behaves in dev vs. production builds.
- [Codemod](https://rep-protocol.dev/reference/codemod.md): Automated codemod to migrate from Vite import.meta.env, CRA process.env.REACT_APP_*, and Next.js NEXT_PUBLIC_* to REP runtime environment variables. Idempotent and non-destructive.

## Specification

- [Overview](https://rep-protocol.dev/spec.md): Formal specification documents for the Runtime Environment Protocol. RFC-0001 core protocol, security model threat analysis, and conformance requirements for implementations.
- [REP-RFC-0001](https://rep-protocol.dev/spec/rfc-0001.md): The core protocol specification for the Runtime Environment Protocol v0.1.0. Variable classification, gateway behaviour, SDK API, wire format, encryption, and deployment patterns.
- [Security Model](https://rep-protocol.dev/spec/security-model.md): Formal threat model for the Runtime Environment Protocol. Seven threat analyses covering XSS, CDN compromise, session key theft, env var leaks, and more. Hardening recommendations.
- [Conformance](https://rep-protocol.dev/spec/conformance.md): MUST-level requirements for REP-conformant gateway and SDK implementations. 10 gateway requirements, 6 SDK requirements, and 5 optional features per RFC 2119.

## Contributing

- [Contributing](https://rep-protocol.dev/contributing.md): How to contribute to the Runtime Environment Protocol. Development setup with pnpm and Go, commit conventions, code style for Go and TypeScript, testing, and the automated release process.

## Optional

- [Payload JSON Schema](https://rep-protocol.dev/schema/rep-payload.schema.json): Wire format of the injected `__rep__` script tag
- [Manifest JSON Schema](https://rep-protocol.dev/schema/rep-manifest.schema.json): Schema for the optional `.rep.yaml` manifest
- [Source repository](https://github.com/RuachTech/rep): Go gateway, TypeScript SDK, adapters, plugins, and examples
- [Releases](https://github.com/RuachTech/rep/releases): Pre-built gateway binaries for Linux, macOS, and Windows