DEV Community: Olamide Adebayo

Stop Shipping Your OS. Ship Only What Runs.

Olamide Adebayo — Wed, 01 Apr 2026 16:50:21 +0000

A practical guide to Docker's scratch base image — what it actually is, why it matters for production Go services, and every hidden pitfall that will catch you out.

92% of IT professionals now ship software in containers. The most common source of container vulnerabilities is not your application code — it is the bloated base image sitting underneath it, full of binaries you never asked for and will never use.

FROM scratch is Docker's answer to that problem. This article walks through what it actually means, when to use it, and the four things that will silently break your production service if you do not account for them upfront.

What actually is `FROM scratch`?

Every Docker image starts from something. ubuntu:22.04 gives you a full Linux userland. alpine:3.19 gives you a stripped-down but still functional shell environment. scratch gives you absolutely nothing.

That is not a metaphor. scratch is a reserved, empty image in Docker. There is no filesystem layer. No shell. No libc. No /bin, no /etc, no /tmp. The only thing inside your final container is exactly what you explicitly copy into it.

Go is uniquely positioned to exploit this. Unlike Node.js or Python, a Go binary compiled with CGO_ENABLED=0 is completely self-contained. It links statically, carries its own runtime, and needs no interpreter. You can drop it into an empty container and it runs.

The size comparison that makes the case

Base image	Approximate size
golang:1.23 (builder)	~630 MB
ubuntu:22.04	~77 MB
alpine:3.19	~7 MB
gcr.io/distroless/static	~2 MB
scratch (your binary only)	~4–8 MB

Smaller images mean faster pulls in CI, reduced cloud egress costs, quicker cold starts in serverless environments, and less pressure on your container registry. Over hundreds of deployments a week, these savings compound noticeably.

The pitfalls nobody warns you about

The appeal of scratch is obvious. It also breaks several silent assumptions your application makes at runtime. Here are the four that will catch you out.

1. TLS certificates

The error: x509: certificate signed by unknown authority

Your Go binary trusts HTTPS endpoints by delegating to the OS certificate store at /etc/ssl/certs. A scratch image has no such directory. The moment your service makes an outbound HTTPS call — to a payment provider, an AWS service, or any external API — it will fail with this error in production while working perfectly in your local environment.

The fix is to copy the CA bundle from your builder stage into the scratch image at the correct path. Once it exists there, Go's TLS stack finds it and everything behaves as expected.

2. Timezone data

The error: panic: time: missing Location in call to Date

Go's time.LoadLocation("Europe/London") looks for the IANA timezone database on disk under /usr/share/zoneinfo. That directory does not exist in scratch. Any application that processes timestamps, schedules jobs, or converts between timezones will panic on startup or at the first timezone operation it attempts.

You have two options: copy the zoneinfo directory from your builder, or embed timezone data directly into the binary using Go's time/tzdata package, which removes the filesystem dependency entirely.

3. Running as root

The problem: Container runs as UID 0 by default.

Without a USER directive, Docker containers run as root. In a standard image this is a one-liner fix. In a scratch image, you cannot create users at build time because there is no adduser or useradd binary. The non-root user must be created in the builder stage, and the relevant /etc/passwd and /etc/group files copied across. A container breakout on a root-running container means the attacker has root on the host node.

4. Dynamic linking and CGO

The error: standard_init_linux.go:211: exec user process caused "no such file or directory"

If your Go code uses CGO — common with drivers like sqlite3 or packages with C bindings — the compiled binary will look for shared libraries like glibc at runtime. Scratch has none of them. The Linux kernel refuses to execute the binary before it even starts. You must build with CGO_ENABLED=0 to produce a fully static binary. Some CGO-dependent packages will need replacing with pure-Go equivalents.

The complete, production-ready Dockerfile

This single pattern addresses all four pitfalls in one pass.

# ── Stage 1: Builder ─────────────────────────────────────────
FROM golang:1.23-alpine AS builder

# CA certs + timezone data — critical for scratch targets
RUN apk add --no-cache ca-certificates tzdata && update-ca-certificates

# Create a non-root user (scratch has no adduser binary)
ENV USER=appuser UID=10001
RUN adduser \
    --disabled-password --gecos "" \
    --home "/nonexistent" --shell "/sbin/nologin" \
    --no-create-home --uid "${UID}" "${USER}"

WORKDIR /app
COPY . .

# CGO_ENABLED=0 produces a fully static binary — non-negotiable for scratch
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o myapp .

# ── Stage 2: The scratch image ────────────────────────────────
FROM scratch

# User identity from builder
COPY --from=builder /etc/passwd /etc/passwd
COPY --from=builder /etc/group /etc/group

# TLS certificate chain
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Timezone database
COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo

# The binary
COPY --from=builder /app/myapp /myapp

# Drop privileges
USER appuser:appuser

ENTRYPOINT ["/myapp"]

One detail worth noting: -ldflags="-s -w" strips debug symbols and DWARF information from the binary, cutting another 20–30% off the final image size with no impact on runtime behaviour. Always include it for production builds targeting scratch.

When scratch is the right choice — and when it is not

Scratch is the right choice when you are deploying a statically linked program you fully control. Pure Go APIs, gRPC services, background workers, and CLI tools are natural fits.

It becomes the wrong choice the moment you need a debugging workflow inside the container. There is no shell, no ls, no curl, no cat. You cannot exec into a scratch container and look around. If your production incident response involves running commands inside a live container, scratch will frustrate you more than it saves.

The rational middle ground: Google's Distroless images sit between Alpine and scratch. They include libc, CA certs, and timezone data but strip the shell and package manager entirely. For teams that occasionally need to exec into containers for diagnostics, Distroless gives most of the security benefit with significantly less build ceremony.

For services at scale where every megabyte and every CVE matters, scratch remains the gold standard.

The security argument, properly framed

The conventional pitch for scratch focuses on image size. The more important argument is attack surface.

A container with no shell cannot be hijacked via shell injection. A container with no package manager cannot have dependencies tampered with at runtime. A container running as a non-root user limits the blast radius of any container escape vulnerability.

Container escapes are rare but not theoretical. When one occurs, the attacker's capability is determined by what exists inside the container. A scratch-based service gives them a single static binary and nothing else.

Consider also supply chain exposure. Every package in your base image is a potential vulnerability. Ubuntu images routinely carry 200+ installed packages, most of them irrelevant to your application. Each one must be patched, monitored, and accounted for in your CVE scanning. Scratch eliminates that debt entirely.

TL;DR

Use a multi-stage Dockerfile. Build with CGO_ENABLED=0. Copy your CA certs, timezone data, and a non-root user definition into the scratch stage. Everything else stays in the builder. The result is a container that carries only your application, runs unprivileged, and gives an attacker essentially nothing to work with.

For Go services, there is very little reason not to do this.

Tags: #docker #go #devops #security

🚨 LiteLLM Supply Chain Attack: A Deep Dive

Olamide Adebayo — Tue, 24 Mar 2026 15:25:12 +0000

Date: March 24, 2026
Target: LiteLLM (Versions 1.82.7 & 1.82.8)
Threat Actor: Suspected TeamPCP (linked to HackerBot-Claw campaign)

⚠️ Live Incident — Updated March 24, 2026: This attack is actively unfolding. PyPI has quarantined the affected versions. If you've used LiteLLM in the last 24 hours, see the Developer Advisory below.

Full post-mortem now published: https://snyk.io/articles/poisoned-security-scanner-backdooring-litellm/

Executive Summary

A widely trusted Python library — LiteLLM — was compromised and distributed with hidden malware.

Anyone installing the affected versions unknowingly:

Executed malicious code automatically
Had sensitive credentials silently stolen — SSH keys, cloud tokens, Kubernetes secrets
Potentially exposed entire cloud environments

The campaign has now expanded from GitHub Actions to include malicious packages on PyPI. PyPI quarantined the affected versions approximately 3 hours after publication — but the window was open long enough.

This wasn't a traditional hack. It was a trust breach at the software supply chain level.

Why This Matters

Modern software is no longer built — it's assembled.

Your application depends on:

Open-source libraries
Package registries (PyPI, npm)
CI/CD pipelines
Third-party APIs

This attack proves a hard truth:

Your security is only as strong as the weakest dependency you trust.

Recent reporting highlights a growing trend: attackers are increasingly targeting popular Python libraries — not for disruption, but for silent credential harvesting at scale. AI-related tooling is a prime target due to high-value API keys.

1. What is a Supply Chain Attack?

Imagine you run a high-security restaurant:

Guards at the doors
Cameras everywhere
Secure cash handling

You're confident no one can break in.

Now imagine someone poisons your ingredients before delivery.

You trust your supplier — so you let it in.

Real World	Software World
Restaurant	Your company / system
Farmer	LiteLLM (trusted library)
Poisoned lettuce	Malicious code

You didn't get hacked. You installed the attack yourself.

2. The Attack: Step-by-Step

Phase 1 — The Breach: Stealing the Keys

Attackers likely obtained a Personal Access Token (PAT) from a maintainer via:

Scanning CI/CD pipelines
Exploiting misconfigurations
Credential leaks in logs or environment variables

This granted them permission to publish code as a trusted maintainer.

Phase 2 — The Infection: The `.pth` Trick

Instead of modifying obvious code, attackers added a file:

litellm_init.pth

Why this is dangerous:

.pth files in Python are automatically executed on startup
No import required
No function call required

Just installing the package = executing the malware

This is what made the attack extremely stealthy.

Phase 3 — The Theft: Credential Harvesting

Once executed, the malware scanned for:

Cloud Credentials

AWS keys
GCP credentials
Azure tokens

AI Secrets

OpenAI API keys
HuggingFace tokens

Infrastructure Access

SSH keys
Environment variables
Local config files

Phase 4 — The Exfiltration: Data Escape

The stolen data was packaged silently and sent to attacker-controlled servers.

In some campaign variants, secrets were written into public CI logs — acting as a delayed dead drop retrieval system.

Your own infrastructure became the attacker's delivery channel.

3. Why This Attack Was So Dangerous

It Targeted the "Middle Layer"

LiteLLM sits between your app and AI providers (OpenAI, Claude, etc.) — giving it direct access to high-value API keys and billing-sensitive tokens.

It Weaponised Best Practices

Developers are told: "Always keep dependencies updated."

Attackers flipped this into: "Updating your dependency installs malware."

Tag Hijacking: The Silent Killer

Attackers overwrote existing version tags. So even this:

pip install litellm==1.82.7

...was no longer safe. Version pinning alone failed completely.

It Exploited Developer Assumptions

Developers assume:

"PyPI packages are safe"
"Pinned versions don't change"
"Nothing runs unless I import it"

All three assumptions were broken.

🔴 Developer Advisory: Act Now

If you have used LiteLLM in the last 24 hours, take these steps immediately.

1. Pin to a Safe Version

Revert to v1.82.6 — the last known clean version:

pip install litellm==1.82.6

2. Rotate All Secrets

If you installed v1.82.7 or v1.82.8, assume all credentials on that machine are stolen:

API keys (OpenAI, HuggingFace, etc.)
Cloud tokens (AWS, Azure, GCP)
SSH keys
Kubernetes secrets

Rotate everything. Immediately.

3. Check for Active Infection

Search your Python environment for the malicious file:

find / -name "litellm_init.pth" 2>/dev/null

Its presence indicates an active infection.

4. Monitor Outbound Network Traffic

Check your egress logs for connections to the known exfiltration domain:

models.litellm.cloud

Any traffic to this domain should be treated as a confirmed breach indicator.

🕸️ The Broader Campaign: Shai-Hulud 2.0

Security researchers have linked this attack to a wider campaign dubbed HackerBot-Claw, also referred to as Shai-Hulud 2.0.

Key intelligence:

Automated bots exploit misconfigured GitHub Actions workflows to steal maintainer tokens
The same group previously compromised Trivy, a widely used container security scanner
Attackers use public GitHub repositories — frequently named with tpcp-docs — as dead drops to store exfiltrated data
This explains the CI log exfiltration technique: your own pipeline becomes the retrieval mechanism

This is not an isolated incident. It is a systematic, automated campaign targeting the open-source toolchain.

4. How to Protect Your Systems

✅ Rule 1: Pin by Hash (Non-Negotiable)

# ❌ Bad
pip install litellm==1.82.7

# ✅ Good
pip install litellm --hash=sha256:<exact_hash>

A hash is an immutable fingerprint. Any code change → hash mismatch → install fails.

This is the single most important control.

✅ Rule 2: Use Scoped Credentials

Most API keys today have too much power. Fix this:

Use least-privilege access
Separate keys per service
Restrict permissions, IP ranges, and usage limits

Example: your chatbot key should cover only inference — not billing, not admin APIs.

Assume every key will leak. Design for containment.

✅ Rule 3: Egress Filtering

Most companies focus on blocking attacks coming in — but ignore data leaving.

Allow outbound traffic only to known APIs (e.g., api.openai.com)
Block everything else by default

If malware tries POST https://models.litellm.cloud/steal → connection denied. Even if compromised, data cannot escape.

✅ Rule 4: Dependency Verification Pipeline

pip install --require-hashes

Also use tools like:

pip-audit
safety
Internal package mirrors

✅ Rule 5: Zero Trust for Dependencies

"Every dependency is untrusted until verified."

No blind updates
No implicit trust in maintainers
Always verify integrity

5. Lessons for Engineering & Leadership

For Engineers

Stop relying on version pinning alone
Audit how dependencies execute code
Treat .pth files, post-install scripts, and hooks as high-risk

For Engineering Leaders

Enforce secure dependency policies org-wide
Invest in internal package mirrors and SBOMs (Software Bill of Materials)
Make security part of CI — not an afterthought

For Non-Technical Leadership

This attack shows you can have perfect internal security and still be compromised via vendors.

This is a business risk, not just a technical one.

Final Takeaway

The LiteLLM attack was not a failure of coding.

It was a failure of trust assumptions in modern software.

The Old Model	The New Reality
"If it installs, it's safe"	"If you didn't verify it, assume it's compromised"

You don't get hacked because your walls are weak.
You get hacked because you trusted what came through the gate.

We Replaced Hours of Manual API Testing With an AI Agent Running Integration Tests in Real Time

Olamide Adebayo — Thu, 19 Mar 2026 00:16:58 +0000

— and it didn't just write the tests. It debugged Kubernetes RBAC, fixed race conditions, and shipped all 40 passing.

Let me tell you what happened this week, because I think it signals something real about where developer workflows are heading.

I'm building a PaaS that lets you deploy MCP (Model Context Protocol) servers on Kubernetes with a single API call. This week we shipped a new feature branch: replica management — the ability to start, stop, restart, and scale running MCP servers.

Standard stuff. But the way we tested it was anything but.

The Old Way: Postman (and Why It Slows You Down)

Most backend engineers know the drill.

You open Postman. You find the right collection. You manually update the Authorization header with a freshly copied token. You click Send on the first endpoint, copy an ID from the response, paste it into the next request, click Send again. You spend 20 minutes setting up a flow that tests 5 endpoints in sequence — not because the logic is hard, but because the tooling is manual.

And that's for tests you've already built.

For a new feature branch? You're starting from scratch. Writing request bodies, thinking through edge cases, figuring out what state needs to exist before you can even test step 3. It eats your afternoon.

Yes, Postman has an MCP server now. That's progress. But it still requires you to open an application, navigate a GUI, and manage state by hand. The interface changed; the friction didn't disappear.

Enter Bruno CLI — and the Shift That Changes Everything

Bruno is an open-source API client. What makes it different isn't the UI — it's that your entire collection lives as plain text .bru files, committed to your repo, right next to your source code.

That one decision unlocks everything.

Because when your tests are files in a repo, an AI agent can read them, write them, run them, and iterate on failures — all without you touching a browser.

Here's the command that ran our entire 10-step integration test suite:

bru run "Replica Management" --env Local --env-var authToken="$TOKEN"

That's it. One line. 40 assertions. 1.3 seconds.

What the Agent Actually Did

We didn't just ask Claude to "write some tests." We gave it access to the running system — the codebase, kubectl, the live API — and let it work.

Here's what happened:

1. It read the feature branch code to understand the new stop/start/restart/scale endpoints before writing a single test.

2. It wrote 10 sequential test steps as .bru files, each building on the last — finding a live deployment, stopping it, checking status, starting it, restarting, scaling up to 2 replicas, scaling back down, validating that stdio transport correctly rejects a scale-to-2 request with a 400 error, then restoring state.

3. Tests failed. The agent debugged them in real time.

The first run showed 401 Unauthorized. The agent found that collection.bru had a hardcoded expired JWT and changed it to {{authToken}} — parameterized via env var.

The second run showed 502 on the start endpoint. The agent ran kubectl to check the operator logs. Found the operator was stuck in Pending because a ClusterRole was missing the apply verb for services and statefulsets. It diagnosed it, documented the fix.

The third run: 502 again, different error. The ScaleMCPServer function was calling GetScale on a Deployment, then UpdateScale — but the operator was reconciling the Deployment 5 times per second, changing its resourceVersion between our two calls. Classic Kubernetes optimistic concurrency conflict. The agent read the Go client code, identified that the retry loop was reusing a stale object, and refactored both ScaleMCPServer and UpdateMCPServer to re-fetch inside the retry closure on every attempt.

40/40. All green.

This Is Not About Replacing Tests — It's About Removing the Gap

Here's what I think gets missed in conversations about AI and testing.

The narrative is usually: "AI writes your unit tests." Fine. But unit tests mock everything. They're fast feedback on logic, not on the real system.

What we're talking about is different. This is an agent that:

Has live access to the running API
Understands the feature branch code
Writes tests that reflect actual system behavior
Runs them against a real Kubernetes cluster
Reads the failure output, forms a hypothesis, digs into source code or infrastructure, makes a fix, and retries

That's the workflow of a senior engineer doing a proper integration testing pass on a feature branch — compressed from hours into minutes.

And critically: the tests it writes don't disappear. They become part of the repo. Every future developer, every future CI run, every future AI agent gets the benefit.

The Deeper Shift: Tests as Living Documentation

When integration tests live as .bru files next to your source code, they stop being a separate concern. They become part of how you describe what your API does.

The test file for our stop endpoint doesn't just assert status: 200. It documents that:

The MCPServer CRD is preserved (not deleted) when stopped
ready_replicas drops to 0 even though replicas config stays at 1
The subdomain and ingress survive the stop for fast restart

That's knowledge that would otherwise live in someone's head, a Notion doc, or nowhere at all.

What This Means for Your Team

If you're still manually clicking through Postman for every feature branch test, consider this:

Move your API collections to Bruno — plain text files, version controlled, portable
Give your AI agent access to run them — bru run is a single shell command
Let the agent write tests against new branches — not one-shot generation, but iterative: run → fail → diagnose → fix → rerun
Commit the tests — they compound. Every feature ships with its integration tests checked in.

The tooling is already there. The AI capability is already there. The gap is just knowing they can work together.

We've published the Bruno skill we use so any Claude Code agent can pick it up instantly:

npx skills add https://github.com/olamide226/agent-skills --skill bruno

Full skill source: github.com/olamide226/agent-skills — bruno/SKILL.md

Join the waitlist for MCPLambda — infrastructure for deploying MCP servers at scale. If you're working on the MCP ecosystem or thinking about developer tooling for AI-native backends, I'd love to connect.

What's your current setup for integration testing feature branches? I'm curious how teams are handling this — drop a comment below.

Tags: #AI #DeveloperTools #APITesting #Kubernetes #BackendEngineering #MCP #ClaudeCode #DevEx #Bruno #Integration Testing

Stop Baking Config Into Your React Builds — Runtime Env Vars for Containerised Frontends

Olamide Adebayo — Thu, 05 Mar 2026 19:21:12 +0000

You know the drill. Your React app needs an API URL. So you reach for import.meta.env.VITE_API_URL, run npm run build, and ship it. Works great — until you need to deploy the same image to staging and production with different config.

Now you're building myapp:staging and myapp:prod. Two images. Two builds. The image that passed your tests is a different binary than the one going to production. Your CD pipeline is lying to you.

This is the dirty secret of React containerisation: every VITE_* / REACT_APP_* / NEXT_PUBLIC_* variable is dead-end string-replaced into your bundle at build time. The browser has no process object. There is no runtime.

The workarounds are all terrible:

envsubst on minified JS — fragile, mutates your container filesystem
fetch('/config.json') at startup — loading delays, race conditions, you're just moving the problem
window.__ENV__ set via a shell script — no standard, no security model, requires Node.js or bash in your prod image

There's a better way.

Introducing REP Protocol

REP (Runtime Environment Protocol) is a lightweight open protocol that injects environment variables into your React app at container startup, not at build time. A tiny Go binary (the gateway) reads your REP_* environment variables when the container boots, encrypts the sensitive ones, and injects them as an inert <script> tag into your HTML before the browser ever sees it.

Your React code stays clean:

import { useRep, useRepSecure } from '@rep-protocol/react';

function App() {
  const apiUrl = useRep('API_URL');                         // synchronous, no loading state
  const { value: analyticsKey } = useRepSecure('ANALYTICS_KEY'); // encrypted, async
}

Same image. Different docker run -e flags. Done.

The Security Tier System

REP uses a prefix convention that forces you to make an explicit security decision for every variable:

Prefix	Tier	Behaviour
`REP_PUBLIC_*`	PUBLIC	Plaintext in page source. Sync access via `useRep()`.
`REP_SENSITIVE_*`	SENSITIVE	AES-256-GCM encrypted. Async access via `useRepSecure()`.
`REP_SERVER_*`	SERVER	Never sent to the browser. Gateway-only.

The prefixes are stripped in your app: REP_PUBLIC_API_URL becomes rep.get('API_URL'). This is key — it means you can't accidentally grab a SERVER variable from client code. The namespace just doesn't exist on the client.

SENSITIVE vars are encrypted with AES-256-GCM at gateway startup using an ephemeral in-memory key. When useRepSecure() is called, the SDK fetches a single-use session key from /rep/session-key (30s TTL, rate-limited, origin-validated) and decrypts the blob in the browser. The plaintext is never stored anywhere.

Building the Todo App

Let's walk through a real example. Here's the full structure of a containerised React todo app using REP.

1. Install the packages

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

2. Write your React components

// App.tsx
import { useRep } from '@rep-protocol/react';

export default function App() {
  // useRep() is synchronous — no loading state, no Suspense, no useEffect
  const appTitle    = useRep('APP_TITLE', 'My App');
  const envName     = useRep('ENV_NAME',  'development');
  const maxTodosStr = useRep('MAX_TODOS', '10');
  const maxTodos    = parseInt(maxTodosStr ?? '10', 10);

  // ...
}

// RepConfigPanel.tsx — shows both tiers in action
import { useRep, useRepSecure } from '@rep-protocol/react';
import { meta } from '@rep-protocol/sdk';

export function RepConfigPanel() {
  // PUBLIC tier — synchronous, available before first render
  const apiUrl = useRep('API_URL', '—');

  // SENSITIVE tier — encrypted in HTML, decrypted on demand
  const { value: analyticsKey, loading, error } = useRepSecure('ANALYTICS_KEY');

  const repMeta = meta(); // injected_at, integrity valid?, hot_reload enabled?

  return (
    <div>
      <p>API URL: {apiUrl}</p>
      <p>
        Analytics key:{' '}
        {loading ? 'fetching…' : error ? 'unavailable' : analyticsKey}
      </p>
      {repMeta && (
        <p>Integrity: {repMeta.integrityValid ? '✓ valid' : '✗ tampered'}</p>
      )}
    </div>
  );
}

useRep() re-renders automatically on hot reload — if the gateway detects a config change via SSE, subscribed components update in the browser without a page refresh.

3. Write the Dockerfile

This is where it gets interesting. The production image is built from scratch — no OS, no shell, no Node.js. Just the Go gateway binary and your static files.

# Stage 1: Download the REP gateway binary
FROM alpine:3.21 AS gateway

ARG GATEWAY_VERSION=0.1.3
ARG TARGETARCH=amd64

RUN apk add --no-cache curl ca-certificates && \
    ARCHIVE="rep-gateway_${GATEWAY_VERSION}_linux_${TARGETARCH}.tar.gz" && \
    curl -fsSL \
      "https://github.com/RuachTech/rep/releases/download/v${GATEWAY_VERSION}/${ARCHIVE}" \
      -o /tmp/gateway.tar.gz && \
    tar -xzf /tmp/gateway.tar.gz -C /tmp && \
    mv /tmp/rep-gateway /rep-gateway && \
    chmod +x /rep-gateway

# Stage 2: Build the React app
FROM node:20-alpine AS app

WORKDIR /app
COPY package.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 3: Minimal runtime image
FROM scratch

COPY --from=gateway /rep-gateway /rep-gateway
COPY --from=app /app/dist /static
COPY --from=gateway /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

USER 65534:65534
EXPOSE 8080

ENTRYPOINT ["/rep-gateway", "--mode", "embedded", "--static-dir", "/static"]

The final image contains:

One Go binary (~5MB)
Your dist/ folder
CA certificates

No Node.js. No nginx. No bash. FROM scratch means the attack surface is essentially zero.

4. Build once, deploy everywhere

docker build -t rep-todo .

# Development
docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_APP_TITLE="REP Todo" \
  -e REP_PUBLIC_ENV_NAME=development \
  -e REP_PUBLIC_API_URL=http://localhost:3001 \
  -e REP_PUBLIC_MAX_TODOS=10 \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_demo_abc123 \
  rep-todo

# Staging — same image, different flags
docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_APP_TITLE="REP Todo (Staging)" \
  -e REP_PUBLIC_ENV_NAME=staging \
  -e REP_PUBLIC_API_URL=https://api.staging.example.com \
  -e REP_PUBLIC_MAX_TODOS=20 \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_staging_xyz789 \
  rep-todo

The exact same rep-todo:latest image runs in both environments. The image that passed your CI tests is literally the binary that goes to production.

Going Further: The Optional `.rep.yaml` Manifest

The gateway works without any manifest — you can stop at step 4 and ship. But if you want typed variables, runtime validation, and bundle scanning, add a .rep.yaml to your project.

# .rep.yaml
version: "0.1.0"

variables:
  APP_TITLE:
    tier: public
    type: string
    default: "REP Todo"

  ENV_NAME:
    tier: public
    type: enum
    required: true
    values: ["development", "staging", "production"]

  API_URL:
    tier: public
    type: url
    required: true

  MAX_TODOS:
    tier: public
    type: number
    default: "10"

  ANALYTICS_KEY:
    tier: sensitive
    type: string

settings:
  strict_guardrails: false  # set to true in production
  hot_reload: true

TypeScript types from your manifest

npx rep typegen

This generates src/rep.d.ts, augmenting the SDK with typed overloads derived directly from your variable declarations:

// src/rep.d.ts — auto-generated, do not edit
declare module "@rep-protocol/sdk" {
  export interface REP {
    // Only declared PUBLIC keys are valid — anything else is a compile-time error
    get(key: "APP_TITLE" | "ENV_NAME" | "API_URL" | "MAX_TODOS"): string | undefined;

    // Only declared SENSITIVE keys are valid here
    getSecure(key: "ANALYTICS_KEY"): Promise<string>;
  }
}

Rename a variable in .rep.yaml, re-run typegen, and TypeScript marks every call site that broke. Wire it into prebuild and types stay in sync automatically.

Runtime validation at container startup

Point the gateway at your manifest and it validates the full variable set before serving a single request:

ENTRYPOINT ["/rep-gateway", "--mode", "embedded", "--static-dir", "/static", "--manifest", "/static/.rep.yaml"]

Or via env var: REP_GATEWAY_MANIFEST=/static/.rep.yaml.

Missing a required variable? The container refuses to start:

manifest validation: manifest validation failed:
  - required variable "ENV_NAME" is not set
  - required variable "API_URL" is not set

Type mismatches, invalid enum values, and regex pattern failures are all caught the same way — hard failures at container startup, before any traffic reaches your app.

Local Development

You don't need Docker to work locally. The CLI wraps the gateway binary and gives you a dev server:

# Copy the example env file
cp .env.example .env.local

# Terminal 1: start Vite as usual
npm run dev

# Terminal 2: start the REP gateway (proxies Vite at :5173)
npx rep dev --port 3000 --env .env.local --proxy http://localhost:5173 --hot-reload

Now open http://localhost:3000. Your app runs through the gateway — config is injected, encryption works, hot reload is live.

Edit .env.local, change REP_PUBLIC_APP_TITLE to something else. The browser updates instantly, no page refresh.

The CLI also includes rep lint, which scans your built bundle for accidentally leaked secrets:

npx rep lint ./dist

It runs Shannon entropy analysis and pattern matching (AWS keys, JWTs, GitHub tokens, Stripe keys, etc.) against your build output. Useful even without a manifest — it catches secrets that slipped into the wrong tier regardless.

What Happens at Runtime (Under the Hood)

When the container starts:

Gateway reads all REP_* environment variables
Classifies them into PUBLIC / SENSITIVE / SERVER (by prefix)
Runs guardrails — entropy scan + known secret format detection — on PUBLIC vars
Generates an ephemeral AES-256 key and HMAC secret (in-memory only, never persisted)
Encrypts SENSITIVE vars into a base64 blob
Computes an HMAC-SHA256 integrity token over canonical JSON
Pre-renders the <script id="__rep__" type="application/json"> tag

On each browser request, the gateway serves your index.html with the script tag injected before </head>. The script type is application/json — the browser does not execute it. It's inert data.

The SDK reads it synchronously on module load:

// This happens on import, before your component tree renders
const script = document.getElementById('__rep__');
const payload = JSON.parse(script.textContent);

useRep() reads from the parsed payload. Zero network calls. Zero loading states.

Migrating an Existing Project

You can adopt REP gradually — it works alongside your existing build-time vars while you migrate component by component. But if you want to move fast, the codemod handles the bulk of the transformation automatically.

Option A — Automated (recommended for larger codebases)

# Vite
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

The codemod rewrites your source files in place. For a Vite project it transforms:

// Before
import.meta.env.VITE_API_URL
import.meta.env.VITE_FEATURE_FLAGS

// After
import { rep } from '@rep-protocol/sdk';

rep.get('API_URL')
rep.get('FEATURE_FLAGS')

It also adds the SDK import where missing and strips the VITE_ / REACT_APP_ / NEXT_PUBLIC_ prefixes from your variable names throughout. After running it, rename your env vars in .env files and CI config accordingly (VITE_API_URL → REP_PUBLIC_API_URL), then wire up the gateway.

Option B — Manual (better for small projects or incremental adoption)

Install the packages and replace calls one file at a time:

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

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

Either way, rep lint ./dist is worth running before shipping to make sure nothing sensitive slipped into the wrong tier. If you add a .rep.yaml, rep typegen gives you typed overloads on top.

Docker Compose — The Twelve-Factor Way

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"

One image. Two services. Config lives in the environment, where it belongs.

The Payoff

Before REP:

Build myapp:staging, build myapp:prod — two different binaries
Config change = rebuild = redeploy
Secrets in window.__ENV__ as plaintext

After REP:

Build once: myapp:latest
Config change = restart container with new env vars
Sensitive vars AES-encrypted, public vars integrity-verified, server vars never leave the gateway

The todo example is in the REP monorepo if you want to clone and run it. Full spec, security model, and integration guide are in spec/.

REP is open source under Apache 2.0. The spec is CC BY 4.0. Contributions welcome.

The Frontend Environment Variable Problem No One Really Solved

Olamide Adebayo — Mon, 02 Mar 2026 17:07:35 +0000

If you've shipped a React, Vue, or Angular app inside a Docker container, you've lived through this:

VITE_API_URL=https://api.staging.example.com npm run build

That npm run build bakes the URL into the JavaScript bundle. Literally — the bundler finds every import.meta.env.VITE_API_URL reference and replaces it with the string "https://api.staging.example.com". Static string replacement. The resulting JS file has no concept of an environment variable. It's just a hardcoded string now.

Which means your Docker image is environment-specific. You can't promote it to production. You need a separate build with the production URL. The image you tested in staging is a different binary than what goes to prod.

This violates the entire point of containers.

The Hack Everyone Writes

Eventually, someone on the team writes a shell script. It looks roughly like this:

#!/bin/sh
# env.sh — runs at container startup
cat <<EOF > /usr/share/nginx/html/config.js
window.__ENV__ = {
  API_URL: "${API_URL}",
  FEATURE_FLAGS: "${FEATURE_FLAGS}",
  ANALYTICS_KEY: "${ANALYTICS_KEY}"
};
EOF
nginx -g 'daemon off;'

Then somewhere in the app:

const apiUrl = window.__ENV__?.API_URL || 'http://localhost:3000';

It works. Thousands of teams use exactly this pattern. But it has problems that compound silently:

No security model. Every variable is plaintext in the page source. Someone puts ANALYTICS_KEY, OAUTH_CLIENT_ID, or occasionally an actual secret behind window.__ENV__ and it's visible to anyone who hits View Source. There's no classification, no distinction between "safe to expose" and "maybe shouldn't be in the HTML."

No integrity. If something modifies that config (a browser extension, a CDN compromise, a supply chain attack), the app has no way to detect it.

No standard. Every team reinvents the wheel with slightly different naming conventions, different variable formats, different injection methods. There's no tooling ecosystem because there's no protocol.

Fragile. Some teams use envsubst or sed directly on the minified JS bundle. One escaped character away from a production incident.

What If There Was a Protocol?

This is why we built REP — the Runtime Environment Protocol.

REP is an open specification (RFC-style, CC BY 4.0) and a reference implementation (Go gateway + TypeScript SDK, Apache 2.0). It replaces the ad-hoc env.sh pattern with a standardised, security-first approach.

The core idea: a lightweight Go binary (~6MB) sits in front of your static file server. At container boot, it reads environment variables, classifies them by security tier, and injects a signed JSON payload into every HTML response. Your application code reads these values through a tiny SDK.

Three Security Tiers

REP classifies variables by their prefix:

# PUBLIC — plaintext in the HTML, synchronous access
REP_PUBLIC_API_URL=https://api.example.com
REP_PUBLIC_FEATURE_FLAGS=dark-mode,new-checkout

# SENSITIVE — encrypted with AES-256-GCM, decrypted on demand
REP_SENSITIVE_ANALYTICS_KEY=UA-12345-1

# SERVER — never sent to the browser, period
REP_SERVER_DB_PASSWORD=supersecret

The prefix IS the classification. REP_PUBLIC_* appears in the page source (like API URLs and feature flags — things that are inherently visible via the network tab anyway). REP_SENSITIVE_* is encrypted in the HTML and requires a short-lived session key to decrypt. REP_SERVER_* never leaves the gateway process — it's the only tier suitable for true secrets.

This is the key difference from every existing solution: you make an explicit security decision for each variable at the naming level. No ambiguity.

Automatic Secret Detection

At startup, the gateway scans your REP_PUBLIC_* values for things that look like they shouldn't be public:

Shannon entropy > 4.5 bits/char? That string looks random — probably a secret.
Starts with AKIA? That's an AWS access key.
Starts with eyJ? That's a JWT.
Starts with ghp_, sk_live_, sk-, xoxb-? GitHub token, Stripe key, OpenAI key, Slack token.

If any heuristic trips, the gateway logs a warning. In --strict mode, it refuses to start. This catches the most common misconfiguration — accidentally putting a secret under the PUBLIC prefix.

HMAC Integrity

Every injected payload carries an HMAC-SHA256 signature and an SRI hash. The SDK verifies these on page load. If something tampered with the config in transit (CDN, proxy, browser extension), the integrity check fails and the SDK flags it.

Hot Config Reload

Optional Server-Sent Events endpoint. Update a Kubernetes ConfigMap, rotate a feature flag, the gateway detects the change and pushes it to every connected browser. The SDK fires onChange callbacks. No page reload needed.

Try It in 5 Minutes

Here's how to go from zero to working demo with Docker.

1. Create a minimal frontend

Any static HTML will do. Create an index.html:

<!DOCTYPE html>
<html>
<head>
  <title>REP Demo</title>
  <script type="module">
    import { rep } from 'https://esm.sh/@rep-protocol/sdk@latest';

    document.getElementById('api-url').textContent = rep.get('API_URL', 'not set');
    document.getElementById('env-name').textContent = rep.get('ENV_NAME', 'not set');
    document.getElementById('flags').textContent = rep.get('FEATURE_FLAGS', 'none');
  </script>
</head>
<body>
  <h1>REP Demo</h1>
  <p>API URL: <strong id="api-url"></strong></p>
  <p>Environment: <strong id="env-name"></strong></p>
  <p>Feature Flags: <strong id="flags"></strong></p>
</body>
</html>

2. Download the gateway binary

Grab the latest release from GitHub:

# Linux/macOS
curl -L https://github.com/ruachtech/rep/releases/latest/download/rep-gateway-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o rep-gateway
chmod +x rep-gateway

Or pull the Docker image:

docker pull ghcr.io/ruachtech/rep/gateway:latest

3. Run it

Without Docker:

REP_PUBLIC_API_URL="https://api.example.com" \
REP_PUBLIC_ENV_NAME="local" \
REP_PUBLIC_FEATURE_FLAGS="dark-mode,beta-checkout" \
./rep-gateway --mode embedded --static-dir . --port 8080 --log-format text

Open http://localhost:8080 — you'll see the values displayed.

With Docker Compose:

# docker-compose.yml
services:
  staging:
    image: ghcr.io/ruachtech/rep/gateway:latest
    command: ["--mode", "embedded", "--static-dir", "/static", "--port", "8080"]
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URL: "https://api.staging.example.com"
      REP_PUBLIC_ENV_NAME: "staging"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode,beta-checkout,debug"
    volumes:
      - ./index.html:/static/index.html:ro

  production:
    image: ghcr.io/ruachtech/rep/gateway:latest
    command: ["--mode", "embedded", "--static-dir", "/static", "--port", "8080"]
    ports:
      - "8081:8080"
    environment:
      REP_PUBLIC_API_URL: "https://api.example.com"
      REP_PUBLIC_ENV_NAME: "production"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode"
    volumes:
      - ./index.html:/static/index.html:ro

docker compose up

Now visit localhost:8080 (staging) and localhost:8081 (production). Same HTML file. Same gateway image. Different configuration. That's the entire value proposition.

4. View Source and inspect

Open View Source on either page. You'll see the injected payload:

<script id="__rep__" type="application/json" data-rep-version="0.1.0"
        data-rep-integrity="sha256-...">
{
  "public": {
    "API_URL": "https://api.staging.example.com",
    "ENV_NAME": "staging",
    "FEATURE_FLAGS": "dark-mode,beta-checkout,debug"
  },
  "_meta": {
    "version": "0.1.0",
    "injected_at": "2026-03-02T10:30:00Z",
    "integrity": "hmac-sha256:...",
    "ttl": 0
  }
}
</script>

Note: type="application/json" means the browser does not execute this script. It's inert data. The SDK reads it via document.getElementById('__rep__').

5. Check the health endpoint

curl http://localhost:8080/rep/health | jq .

{
  "status": "healthy",
  "version": "0.1.0",
  "variables": {
    "public": 3,
    "sensitive": 0,
    "server": 0
  },
  "guardrails": {
    "warnings": 0,
    "blocked": 0
  },
  "uptime_seconds": 42
}

Using the SDK in a Real App

For a real React/Vue/Svelte app, install the SDK:

npm install @rep-protocol/sdk

Then replace your build-time env var references:

// Before (build-time, environment-specific)
const apiUrl = import.meta.env.VITE_API_URL;

// After (runtime, environment-agnostic)
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');

rep.get() is synchronous. No async. No loading states. No Suspense wrapper needed. The value is available the instant the module loads because the SDK reads the <script> tag from the DOM — which is already there before your JavaScript executes.

For encrypted values:

// Fetches a session key, decrypts, caches in memory
const analyticsKey = await rep.getSecure('ANALYTICS_KEY');

For hot reload:

rep.onChange('FEATURE_FLAGS', (newValue, oldValue) => {
  console.log(`Flags changed: ${oldValue} → ${newValue}`);
  // Re-render, toggle UI, whatever you need
});

The SDK is 1.5KB gzipped with zero runtime dependencies.

Adding It to Your Existing Dockerfile

You don't need to rewrite anything. Just add two lines to your existing multi-stage Dockerfile:

FROM node:22-alpine AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build

# Add REP gateway
FROM ghcr.io/ruachtech/rep-gateway:latest
COPY --from=build /app/dist /static
EXPOSE 8080
ENTRYPOINT ["rep-gateway", "--mode", "embedded", "--static-dir", "/static"]

Your build step stays identical. No --build-arg for API URLs. No .env.production. The image is environment-agnostic. Configure it at runtime via environment variables — exactly how containers are supposed to work.

The Security Model Is Honest

I want to be upfront about what REP protects and what it doesn't.

PUBLIC vars are in the page source. By design. Don't put secrets here. These are for API URLs, feature flags, app versions — things that are visible in the network tab regardless.

SENSITIVE vars raise the bar, but aren't a vault. A sophisticated attacker with XSS can call rep.getSecure() and exfiltrate the result. But the encryption prevents casual exposure (View Source, DOM scrapers, browser extensions scanning the page), and the session key mechanism makes intentional access auditable — every key request is logged with IP, origin, and timestamp. Session keys are single-use and expire in 30 seconds.

SERVER vars never reach the browser. This is the only tier for true secrets. If you need a value client-side that would be catastrophic if leaked, reconsider whether it should be client-side at all.

The full threat model covers 7 specific threats with mitigations and residual risks. We deliberately don't claim browser-side encryption is bulletproof — because it isn't.

Compared to What's Out There

The most common question: "How is this different from X?"

vs. shell scripts / envsubst / window.ENV: Same injection concept, but REP adds security classification, encryption, integrity verification, secret detection, and a standard SDK. The injection is 10% of REP. The security layer is 90%.

vs. @import-meta-env/unplugin: The most sophisticated existing tool. But it's a build-tool plugin — you install it into Vite or Webpack and it modifies your build pipeline. REP doesn't touch your build at all. It operates on already-built artifacts at the infrastructure layer. They're complementary, not competing.

vs. SSR frameworks (Next.js, Nuxt): SSR solves this for frameworks that support it. But not all apps need SSR, it couples you to a specific framework, and many organisations have existing SPAs they can't migrate. REP works with any SPA.

vs. "just fetch /config.json at startup": Works, but adds a network dependency at app init (loading delay, race conditions, requires error handling). rep.get() is synchronous — no fetch, no loading state.

What's in the Box

Gateway: Go binary (~6MB). Zero external dependencies. Proxy mode (in front of nginx/caddy) or embedded mode (serves files directly). FROM scratch compatible.
SDK: TypeScript. Zero runtime deps. ~1.5KB gzipped. Synchronous public access, async encrypted access.
CLI: rep validate, rep typegen, rep lint, rep dev. Full local dev workflow.
Adapters: First-party React (useRep), Vue (useRep), and Svelte (repStore) with hot-reload-aware hooks.
Specification: Full RFC-style document. 14 sections. CC BY 4.0.
Security Model: 7 threat analyses with honest residual risk assessments.

Full docs at rep-protocol.dev. Source at github.com/ruachtech/rep.

We'd Love Feedback

REP is early and opinionated. We're looking for feedback on:

The security model — are we being honest enough about the limitations? Are there threats we've missed?
The SDK API — is rep.get() / rep.getSecure() the right developer experience?
Edge cases — what happens with your specific framework, bundler, or deployment setup?
The spec — is anything ambiguous or under-specified?

File issues, open PRs, or just tell us we're wrong about something. The best outcome is that this becomes a community standard rather than one team's opinion.

REP is open source under Apache 2.0, built by Ruach Tech. The specification is licensed under CC BY 4.0.