You ship fast with AI coding tools. VibeWarden adds the security layer you skipped:
TLS, authentication, rate limiting, WAF, secrets management, and AI-readable audit logs —
all in a single binary that sits next to your app.
Quick Start
Path 1 — Generate a prompt (easiest)
Go to vibewarden.dev/start and fill in two fields.
The page generates a ready-to-paste prompt tailored to your app and stack.
For tooling integrations that cannot ship a vibew binary, fetch the pre-rendered
release artifacts and substitute the {{prjname}}, {{description}}, and {{domain}}
placeholders before pasting:
https://github.com/vibewarden/vibewarden/releases/latest/download/agent-kickoff-dev.txthttps://github.com/vibewarden/vibewarden/releases/latest/download/agent-kickoff-deploy.txt
These filenames are public API (ADR-101). See docs/agent-kickoff.md for substitution details.
Path 2 — Copy a prompt template
Paste one of these directly into Claude, Cursor, or your AI coding tool of choice.
Existing app:
Add VibeWarden security sidecar to this project.
VibeWarden is open source (Apache 2.0).
GitHub: https://github.com/vibewarden/vibewarden
Docs: https://vibewarden.dev/llms-full.txt
Install: npm install -g @vibewarden/cli
(no Node.js? curl -fsSL https://vibewarden.dev/install.sh | sh)
Setup: vibew wrap --upstream 3000
Run: vibew dev
New project:
Build [your app idea] with VibeWarden as the security sidecar.
VibeWarden is open source (Apache 2.0).
GitHub: https://github.com/vibewarden/vibewarden
Docs: https://vibewarden.dev/llms-full.txt
Install: npm install -g @vibewarden/cli
(no Node.js? curl -fsSL https://vibewarden.dev/install.sh | sh)
Setup: mkdir myapp && cd myapp && vibew init
Run: vibew dev
Path 3 — Manual setup
# macOS / Linux — with npm (pin a version with @X.Y.Z)
npm install -g @vibewarden/cli
# ...or without Node.js
curl -fsSL https://vibewarden.dev/install.sh | sh
# New project
mkdir myapp && cd myapp
vibew init
vibew dev
Your app is now behind VibeWarden at https://localhost:8443. Done.
Both paths install the same binary from the same GitHub Release, verified against
its published SHA-256 checksum. The npm package additionally pins the checksum in
the published tarball and ships with npm provenance. See
docs/getting-started.md for pinning, mirrors,
and the --ignore-scripts fallback.
Windows support is planned — see #667 (winget)
and #668 (Scoop).
VibeWarden currently builds for macOS and Linux only.
Faster iteration after the first run
Once the stack is running, build locally for faster rebuilds instead of waiting for
the full multi-stage Docker build:
go build -o bin/myapp ./cmd/myapp # fast local build (seconds, not minutes)
vibew build && vibew dev # package the artifact and restart the stack
Use vibew build && vibew dev whenever you change code. Use vibew dev alone only when
you add new services or change vibewarden.yaml.
Docker images are published to ghcr.io/vibewarden/vibewarden as multi-arch manifests
covering linux/amd64 and linux/arm64. Docker pulls the correct image automatically
on both x86-64 servers and ARM64 machines (Apple Silicon, AWS Graviton).
What init / wrap generates
Use vibew init for a new directory (creates its own git repo). Use vibew wrap to add VibeWarden to an existing project in place.
| File | vibew init | vibew wrap |
|---|
vibewarden.yaml | yes | yes |
vibewarden.production.yaml | yes | — |
.gitignore | yes | yes (created or updated) |
vibew (macOS/Linux wrapper script) | — | yes |
vibew.ps1 (PowerShell wrapper) | — | yes |
vibew.cmd (Windows batch wrapper) | — | yes |
AGENTS.md | yes (created or updated) | yes (created or updated) |
AGENTS-VIBEWARDEN.md | yes (always overwritten) | yes (always overwritten) |
PROJECT.md | yes (only with --describe) | — |
runs git init | yes | — |
Wrapper scripts are omitted when vibew wrap --skip-wrapper is given.
Running vibew dev or vibew generate creates runtime files under
.vibewarden/generated/ (gitignored):
.vibewarden/generated/
docker-compose.yml # Full stack: VibeWarden + Kratos + Postgres
kratos/kratos.yml # Ory Kratos config
kratos/identity.schema.json # Identity schema
Do not edit generated files — re-run vibew generate after changing vibewarden.yaml.
How It Works
Ingress (inbound traffic):
flowchart LR
Internet --> VW
subgraph VW["VibeWarden :8443"]
TLS["TLS termination"]
Auth["Auth (JWT / Kratos)"]
RL["Rate limiting"]
WAF["WAF"]
SH["Security headers"]
Audit["Audit trail"]
end
VW --> App["Your App :3000"]
Egress (outbound traffic):
flowchart LR
App["Your App :3000"] --> VW
subgraph VW["VibeWarden :8081"]
Allow["Route allowlist"]
SSRF["SSRF protection"]
Secret["Secret injection"]
TLS["TLS enforcement"]
CB["Circuit breaker"]
RL["Rate limiting"]
PII["PII redaction"]
end
VW --> APIs["External APIs"]
VibeWarden is a local sidecar — it always runs on the same machine as your app.
Your app talks only to localhost for both inbound and outbound traffic.
It never holds external secrets or connects directly to third-party APIs.
Feature Matrix
| Feature | Details |
|---|
| Reverse proxy | Embedded Caddy — programmatic config, no Caddyfile |
| TLS | Let's Encrypt (prod), self-signed (dev), or external (Cloudflare, ACM, …) |
| Authentication | none, jwt (any OIDC provider), kratos (self-hosted), api-key |
| Rate limiting | Token-bucket, per-IP and per-user; in-memory or Redis-backed |
| WAF | Pattern detection for SQLi, XSS, path traversal; block or detect mode — enabled by default in detect mode |
| Security headers | HSTS, CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy, CORS |
| Secrets management | Built-in AES-256-GCM store (default) or OpenBao -- inject secrets as headers or env vars |
| Egress proxy | Outbound HTTP with mTLS, circuit breaker, retry, SSRF protection, PII redaction |
| Resilience | Circuit breaker, retry with jitter, timeout middleware, aggregate health endpoint |
| Observability | Prometheus metrics, OpenTelemetry traces + logs, Grafana dashboards, Jaeger/Tempo |
| AI-readable logs | Versioned JSON schema: schema_version, event_type, ai_summary, payload |
| Audit log sinks | JSON file, OTel logs, webhook (HMAC-signed) with retry |
| Admin API | User management at /_vibewarden/admin/* (token-protected — X-Admin-Key or Authorization: Bearer) |
| Docker images | Multi-arch: linux/amd64 and linux/arm64 (Apple Silicon, AWS Graviton) |
| Docker Compose | Profile-based: --profile observability |
| IP filter | Allowlist / blocklist by IP or CIDR range |
| Body size limiting | Global and per-path request body size limits |
| Input validation | Content-type enforcement and request size limits |
| Maintenance mode |
Authentication Modes
| Mode | When to use |
|---|
none | Fully public apps |
jwt | Any OIDC provider — Auth0, Keycloak, Firebase, Cognito, Okta, Supabase, … |
kratos | Self-hosted identity with login / registration UI via Ory Kratos |
api-key | Machine-to-machine requests |
The jwt mode works with any OIDC-compatible provider:
auth:
mode: jwt
jwt:
jwks_url: "https://your-provider/.well-known/jwks.json"
issuer: "https://your-provider/"
audience: "your-api-identifier"
public_paths:
- /static/*
- /health
Your app receives authenticated user info via headers:
| Header | Source claim | Description |
|---|
X-User-Id | sub | Subject identifier |
X-User-Email | email | Primary email address |
X-User-Verified | email_verified | Email verification status (true/false) |
X-User-Role | traits.role | User role (Kratos only; defaults to user) |
See docs/identity-providers.md for Auth0, Keycloak,
Firebase, Cognito, Okta, Supabase, and Kratos step-by-step guides.
Comparison with Alternatives
| VibeWarden | nginx | Traefik | Cloudflare Tunnel |
|---|
| Target user | Vibe coders / indie devs | Ops / sysadmin | Container-native teams | Any |
| Setup time | 3 commands | Hours of config | Moderate | Minutes |
| Auth out of the box | Yes (OIDC, Kratos, API key) | No | Partial (forward auth only) | No |
| WAF | Yes | Paid (NGINX Plus) | No | Paid (Cloudflare WAF) |
| Secrets management | Yes (built-in + OpenBao) | No | No | No |
| AI-readable audit logs | Yes (versioned schema) | No | No | No |
| Egress proxy + SSRF guard | Yes | No | No | No |
| Self-hosted | Yes | Yes | Yes | No |
| Open source | Apache 2.0 | BSD-2 core | Apache 2.0 | Proprietary |
| Cost | Free (OSS core) | Free | Free | Free tier + paid |
VibeWarden is opinionated and purpose-built for the vibe-coding workflow.
If you need a general-purpose load balancer or a CDN edge, use the right tool for the job.
Which command do I need?
| Scenario | Command |
|---|
| Starting a new project | vibew init |
| Adding the sidecar to an existing app | vibew wrap |
| Adding a feature to an existing config | vibew add <feature> |
Use vibew init when you have nothing yet -- it scaffolds the sidecar config and
agent-instruction files (no app code, no Dockerfile; you write those per the
application contract in AGENTS-VIBEWARDEN.md). Use vibew wrap when you already
have an app and just want to add VibeWarden. Use vibew add to enable individual
features after the initial setup.
CLI Reference
| Command | Description |
|---|
vibew init | Scaffold a new project with VibeWarden (in current directory) |
vibew wrap | Add VibeWarden sidecar to an existing project |
vibew add auth | Enable authentication |
vibew add rate-limiting | Enable rate limiting |
vibew add tls --domain app.yourcompany.com | Enable TLS (use a domain you control; Let's Encrypt rejects example.com) |
vibew add metrics | Enable Prometheus metrics |
vibew add waf [--mode block|detect] | Enable the Web Application Firewall (default mode: detect) |
vibew add admin | Enable admin API |
vibew generate | Regenerate docker-compose.yml from config |
vibew build | Build the Docker image for the app |
vibew dev | Start local dev environment |
vibew dev --rebuild | Stop stack, remove app image, rebuild, start — recovery for image-identity mismatch (v0.18.3+) |
vibew bundle | Produce a self-contained Docker Compose deploy artifact under .vibewarden/bundle/ (walkthrough) |
vibew probe | One-shot HTTPS health check of /_vibewarden/health via Go's TLS stack (bypasses macOS LibreSSL friction). --env <name> probes a named environment overlay. |
vibew status | Show health of all components (richer dev-stack overview; use vibew probe for one-shot HTTPS verification) |
vibew doctor | Diagnose common issues. --preflight <env> adds pre-deploy validation (DNS, port 443, target platform, image arch, TLS email) against the named env overlay. |
vibew logs [--tail N] [--follow] [--since <duration>] [<service>...] |
AI Agent Context
vibew wrap generates context files for your AI coding assistant. When you say
"add a login page," the AI knows to use Kratos flows instead of building auth from scratch.
VibeWarden writes two files that any modern AI coding agent (Claude Code, Cursor,
Aider, Continue, etc.) will read: AGENTS.md (conventional, tool-agnostic)
and AGENTS-VIBEWARDEN.md (VibeWarden-specific context).
Regenerate after config changes:
./vibew context refresh
Demo
cd examples/demo-app
./vibew build
./vibew dev
# Open https://localhost:8443
vibew build builds the demo app Docker image. vibew dev then generates the
runtime configuration under .vibewarden/generated/ and starts the full Docker
Compose stack.
The demo includes a Vulnerability Lab with live SQLi, XSS, and path traversal
examples — and shows VibeWarden blocking them.
Example apps
Minimal reference apps showing VibeWarden in front of common stacks:
Each example exposes /health, /public, and /protected endpoints and
includes a vibewarden.yaml and a 3-step quick start README.
Architecture
VibeWarden follows hexagonal architecture (ports and adapters) with DDD:
cmd/vibewarden/ — CLI entrypoint
internal/
domain/ — Pure domain logic (zero external deps)
ports/ — Interface definitions (inbound + outbound)
adapters/ — Implementations (Caddy, Kratos, Postgres, Builtin secrets, OpenBao, ...)
app/ — Application services (use cases)
config/ — Config loading and validation
plugins/ — Plugin registry and lifecycle
migrations/ — Database migrations (golang-migrate)
Architectural decisions are documented in DECISIONS.md.
Docs
Contributing
See CONTRIBUTING.md for development setup, coding standards,
and how to submit changes.
Security
To report a vulnerability, see SECURITY.md for our responsible
disclosure policy and contact details.
License
Apache 2.0 — see LICENSE.
