VibeWarden

Security sidecar for vibe-coded apps.
You vibe, we warden.

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.txt
• https://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.

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

Authentication Modes

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:

See docs/identity-providers.md for Auth0, Keycloak, Firebase, Cognito, Okta, Supabase, and Kratos step-by-step guides.

Comparison with Alternatives

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?

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

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.