REP — Runtime Environment Protocol

Quick Start

1. Install the SDK

npm install @rep-protocol/sdk

2. Replace your env var calls

- const apiUrl = import.meta.env.VITE_API_URL;
+ import { rep } from '@rep-protocol/sdk';
+ const apiUrl = rep.get('API_URL'); // synchronous, no loading state

3. Add the gateway to your Dockerfile

FROM node:22-alpine AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY --from=ghcr.io/ruachtech/rep/gateway:latest /usr/local/bin/rep-gateway /usr/local/bin/rep-gateway
ENTRYPOINT ["rep-gateway"]
CMD ["--upstream", "nginx", "--port", "8080"]

4. Pass config at runtime

docker run -p 8080:8080 \
 -e REP_PUBLIC_API_URL=https://api.example.com \
 -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta \
 -e REP_SENSITIVE_ANALYTICS_KEY=UA-12345-1 \
 myapp:latest

Packages

SDK Usage

Core SDK (any framework)

import { rep } from '@rep-protocol/sdk';
// PUBLIC vars — synchronous, no async, no loading state
const apiUrl = rep.get('API_URL');
const flags = rep.get('FEATURE_FLAGS');
// SENSITIVE vars — encrypted, decrypted on demand
const key = await rep.getSecure('ANALYTICS_KEY');
// Hot reload — react to config changes without page refresh
rep.onChange('FEATURE_FLAGS', (newValue, oldValue) => {
 console.log(`Flags changed: ${oldValue} → ${newValue}`);
});

React

npm install @rep-protocol/sdk @rep-protocol/react

import { useRep, useRepSecure } from '@rep-protocol/react';
function App() {
 const apiUrl = useRep('API_URL');
 const flags = useRep('FEATURE_FLAGS', 'defaults');
 const { value: analyticsKey, loading } = useRepSecure('ANALYTICS_KEY');
 // Auto re-renders on hot reload config changes
 return <div>API: {apiUrl}</div>;
}

Vue

npm install @rep-protocol/sdk @rep-protocol/vue

<script setup>
import { useRep, useRepSecure } from '@rep-protocol/vue';

const apiUrl = useRep('API_URL');
const analyticsKey = useRepSecure('ANALYTICS_KEY');
</script>
<template>
 <div>API: {{ apiUrl }}</div>
</template>

Svelte

npm install @rep-protocol/sdk @rep-protocol/svelte

<script>
 import { repStore, repSecureStore } from '@rep-protocol/svelte';

 const apiUrl = repStore('API_URL');
 const analyticsKey = repSecureStore('ANALYTICS_KEY');
</script>
<div>API: {$apiUrl}</div>

How Variables Work

Migration

# Vite project
npx @rep-protocol/codemod --framework vite --src ./src
# Create React App
npx @rep-protocol/codemod --framework cra --src ./src
# Next.js
npx @rep-protocol/codemod --framework next --src ./src

CLI

npm install -D @rep-protocol/cli
# Local dev server (wraps the gateway)
npx rep dev --env-file .env
# Scan your built bundle for leaked secrets
npx rep lint ./dist
# Validate your .rep.yaml manifest
npx rep validate
# Generate TypeScript types from your manifest
npx rep typegen

Deployment

Docker Compose — same image, per-environment config

services:
 frontend-staging:
 image: myapp:latest
 environment:
 REP_PUBLIC_API_URL: "https://api.staging.example.com"
 REP_PUBLIC_FEATURE_FLAGS: "dark-mode,beta-checkout"
 REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-staging"
 REP_SERVER_INTERNAL_SECRET: "never-reaches-browser"
 frontend-prod:
 image: myapp:latest # SAME IMAGE
 environment:
 REP_PUBLIC_API_URL: "https://api.example.com"
 REP_PUBLIC_FEATURE_FLAGS: "dark-mode"
 REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-prod"
 REP_SERVER_INTERNAL_SECRET: "also-never-reaches-browser"

Minimal FROM scratch container

FROM node:22-alpine AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build
FROM scratch
COPY --from=ghcr.io/ruachtech/rep/gateway:latest /usr/local/bin/rep-gateway /rep-gateway
COPY --from=build /app/dist /static
USER 65534:65534
EXPOSE 8080
ENTRYPOINT ["/rep-gateway", "--mode", "embedded", "--static-dir", "/static"]

Gateway modes

The Problem REP Solves

Why existing solutions fall short

Security Model

Specification

Examples

Contributing

Development setup

git clone https://github.com/ruachtech/rep.git
cd rep
pnpm install # requires pnpm >= 9.0.0
pnpm -r build # build all packages
pnpm -r test # test all packages
# Gateway (requires Go >= 1.24.5)
cd gateway && make test

License