<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/banner-dark.svg">
    <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/banner-light.svg" alt="Vibecarbon" width="200" />
  </picture>
</p>

<p align="center"><strong>Build the next big thing.</strong></p>

<p align="center">Launch full-stack apps in minutes on the VPS provider of your choice. Auth, billing, and AI-guardrails built-in. Automated backup, restore, scale, replication, and failover.</p>

<p align="center">
  <a href="https://www.npmjs.com/package/vibecarbon"><img src="https://img.shields.io/npm/v/vibecarbon?color=0a7ea4&label=npm" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/vibecarbon"><img src="https://img.shields.io/badge/npm-provenance%20attested-0a7ea4" alt="npm provenance attested (SLSA build provenance via Trusted Publishing)" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/hyperformant/vibecarbon"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.scorecard.dev%2Fprojects%2Fgithub.com%2Fhyperformant%2Fvibecarbon&query=%24.score&label=openssf%20scorecard&color=informational" alt="OpenSSF Scorecard" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" /></a>
  <a href="https://discord.gg/up8Z9sX6M6"><img src="https://img.shields.io/badge/discord-join%20the%20community-5865F2" alt="Join the vibecarbon Discord" /></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> ·
  <a href="#commands">Commands</a> ·
  <a href="#key-benefits">Benefits</a> ·
  <a href="#performance">Performance</a> ·
  <a href="#license">License</a>
</p>

---

Vibecarbon is a full-stack SaaS starter that combines React 19, Vite, Tailwind v4, Hono, Better Auth, and your own Postgres, with automated DevOps built in.

Skip the choice between vendor lock-in and DIY infrastructure. Ship an application with authentication, billing, teams, email, blog, docs, and i18n already wired up, then put it in production without a dedicated DevOps engineer.

It's built for the way software gets written now: AI agents work inside mandatory guardrails (row-level security on every table, secret scanning before anything is committed, confirmation gates on destructive operations), so building fast never has to mean shipping leaks.

Vibecarbon handles Docker Compose and Kubernetes, high availability with one-command failover, worker scaling, and automated backups. The complete stack stays self-contained under one flag you chose, yours to keep, move, or delete. Choose the provider underneath, and choose again whenever you want: your infrastructure choice stays reversible.

---

## Four Commitments, Enforced by Design

<table>
  <tr>
    <td width="112" align="center">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/sovereign-dark.svg">
        <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/sovereign-light.svg" alt="Sovereign" width="88" height="88" />
      </picture>
    </td>
    <td><strong>Sovereign</strong> · <em>Privacy within borders</em><br />Full-stack self-contained. Infrastructure, code, data, and integrations under your complete control.</td>
  </tr>
  <tr>
    <td width="112" align="center">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/agnostic-dark.svg">
        <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/agnostic-light.svg" alt="Agnostic" width="88" height="88" />
      </picture>
    </td>
    <td><strong>Agnostic</strong> · <em>Modular and portable</em><br />Swap components, move hosting providers. All the batteries included, but easily changed.</td>
  </tr>
  <tr>
    <td width="112" align="center">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/grounded-dark.svg">
        <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/grounded-light.svg" alt="Grounded" width="88" height="88" />
      </picture>
    </td>
    <td><strong>Grounded</strong> · <em>Rooted in transparency</em><br />Open source under MIT, CLI and template alike. Everything transparent all the way down.</td>
  </tr>
  <tr>
    <td width="112" align="center">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/agentic-dark.svg">
        <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/pillars/agentic-light.svg" alt="Agentic" width="88" height="88" />
      </picture>
    </td>
    <td><strong>Agentic</strong> · <em>AI-native guardrails</em><br />Security and governance built in. Architected for software built by agents.</td>
  </tr>
</table>

---

## Quick Start

**Prerequisites**

- **Node.js 24.15+** and **Docker** with Compose 2.24.4+ for `create` and local development (`up`).
- **[Pulumi CLI](https://www.pulumi.com/docs/install/)** is required for any cloud deploy (`curl -fsSL https://get.pulumi.com | sh`). It is not bundled.
- **`kubectl` 1.24+** additionally for the `k8s` / `k8s-ha` modes.
- **Linux, macOS, or Windows via [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)**. Native Windows is not supported.

**Zero → production in five commands:**

```bash
# 1. Install the CLI globally
npm install -g vibecarbon

# 2. Create a new project
vibecarbon create my-app

# Lost at any point? Run vibecarbon ? (vibecarbon next on zsh)

# 3. Start local development
cd my-app
vibecarbon up

# 4. Deploy an environment
vibecarbon deploy

# 5. Tear down an environment
vibecarbon destroy
```

> [!TIP]
> Every command takes `-h` for detailed usage: try `vibecarbon deploy -h`.

---

## Commands

```bash
vibecarbon <command> [options]
```

### Dev: create, run, and evolve your project

<!-- BEGIN GENERATED: commands dev -->
| Command | What it does |
| :------ | :----------- |
| **`?`** / **`next`** | Tell me what to do next, and offer to run it |
| **`create <project-name>`** | Create a new Vibecarbon project |
| **`up`** | Start the local development environment |
| **`down`** | Stop the local development environment |
| **`down -orphans`** | Remove local stacks whose project folder is gone or moved |
| **`status`** | Show project and deployment status |
| **`reset`** | Reset the local environment (removes all data) |
| **`add [feature]`** | Add features (observability, redis) |
| **`remove [feature]`** | Remove features from a project |
| **`configure`** | Configure external services and settings: billing, OAuth, SMTP, CI/CD, globalization, and more |
| **`upgrade`** | Upgrade infrastructure files to the latest template |
| **`telemetry [on\|off]`** | Control anonymous usage analytics (status by default) |
<!-- END GENERATED: commands dev -->

### Deploy: take an environment to the cloud (and back)

<!-- BEGIN GENERATED: commands deploy -->
| Command | What it does |
| :------ | :----------- |
| **`deploy [env]`** | Deploy an environment (interactive picker for mode and region) |
| **`destroy [env]`** | Tear down a cloud environment |
| **`backup [env]`** | Create, list, or download database backups |
| **`restore [env]`** | Restore the database from a backup |
| **`failover [env]`** | Initiate failover to the standby region |
| **`scale [env]`** | Scale worker nodes and instance sizes |
<!-- END GENERATED: commands deploy -->

### Debug: look under the hood

<!-- BEGIN GENERATED: commands debug -->
| Command | What it does |
| :------ | :----------- |
| **`shell [env]`** | Open an interactive bash with KUBECONFIG and cloud credentials exported |
| **`diagnose [env]`** | Dump cluster state (nodes, pods, Flux, network) to ~/.vibecarbon/diag-* |
| **`console <node>`** | Open Hetzner's web VNC console for a node |
| **`access [subcommand]`** | Manage the SSH and k8s-API operator-CIDR allowlist |
<!-- END GENERATED: commands debug -->

> [!WARNING]
> `reset` and `destroy` are destructive. Both are confirmation-gated, but read the prompt before you say yes.

---

## Who It's For

**Indie Hackers & Solopreneurs**
Ship fast and control the whole stack. Launch a production-grade MVP this weekend.

**Startup Founders & Small Teams**
Multi-tenant organizations, auto-scaling, and high availability when you need it, without a dedicated DevOps engineer.

**Agencies & Consultancies**
One stack for every client project. Consistent, production-ready foundation with easy handoff.

---

## Where Vibecarbon Fits

If you already self-host with tools like [Coolify](https://coolify.io) or [Dokploy](https://dokploy.com), Vibecarbon lives in the same world: the stack, the state, and the data are yours, with no platform lock-in. The difference is where it starts.

| | You bring | You get |
|---|---|---|
| **Coolify / Dokploy** | An app you've already built | A self-hosted PaaS dashboard that deploys it |
| **Vibecarbon** | An idea | The SaaS codebase itself (auth, billing, teams, admin) plus a CLI that deploys and operates it across Hetzner, DigitalOcean, Linode, Vultr, or Scaleway, from a single Docker Compose server to Kubernetes with one-command failover (mode support varies by provider; see [Architecture](#architecture)), switchable per environment |

Same family, different starting point. If your app already exists, those tools are great homes for it. If you're starting a SaaS from zero, Vibecarbon hands you the application *and* the infrastructure.

---

## Key Benefits

### Application Layer
- Auth (email, OAuth, magic links, MFA) + brute force protection
- Multi-provider billing (Stripe, Paddle, Polar) with subscriptions, checkout, and plan gating
- Multi-tenant organizations with RBAC
- Admin panel with user impersonation, notifications, jobs, contact, newsletter, and infrastructure dashboard
- MDX blog, changelog, documentation, and legal pages (privacy policy, terms of service)
- Internationalization (i18n) with language switcher
- Background jobs via pg_cron (zero extra infrastructure)

<details>
<summary><strong>…and 8 more</strong>: onboarding, uploads, email, newsletter, search, analytics, SEO</summary>

- Guided onboarding flow
- Contact form with admin panel and email notifications
- Newsletter with double opt-in, admin compose/send, and CSV export
- File uploads via S3-compatible object storage (your provider's object storage: Hetzner, DigitalOcean, Linode, Vultr or Scaleway)
- Transactional email (SMTP)
- Client-side docs search with Cmd+K shortcut
- Product analytics (Plausible, cookie-free and privacy-focused)
- SEO (meta tags, sitemap, RSS feed)

</details>

### Infrastructure
- New environments in minutes, and warm redeploys in seconds (<!-- perf:warm-deploy:hetzner/k8s -->11.1s<!-- /perf --> k8s / <!-- perf:warm-deploy:hetzner/compose -->25.8s<!-- /perf --> compose, [measured](#performance))
- Security hardened from day one, with automatic operator CIDR firewalling
- Automated deployments via CI/CD
- Auto-scaling (2-10+ replicas)
- Multi-region high availability with one-command failover
- VPS-native, with root access on every machine and no hidden control plane
- Privacy within borders: you pick the region, backups included
- Continuous S3 WAL-G backup & point-in-time restore
- Optional monitoring dashboards (Grafana, Prometheus, Loki) via the observability add-on
- Modular and portable, so you can change providers without a rewrite

### Developer Experience
- Agent rules for Claude Code, Cursor, Windsurf, and Copilot
- AI-native guardrails: security rules in `AGENTS.md`, confirmation-gated destroys
- 50+ Shadcn UI components
- Full TypeScript across client and server
- Biome linting/formatting, Vitest test suite

---

## Architecture

One CLI, four deploy modes, picked per environment. Every mode includes automated SSL and backups; monitoring dashboards are an optional add-on. Compose HA gives the same high-availability architecture as Kubernetes HA without needing a Kubernetes cluster, so it runs on every provider, including ones with no Kubernetes support at all; select it explicitly with `-mode compose-ha`.

<p align="center">
  <img src="https://raw.githubusercontent.com/hyperformant/vibecarbon/main/docs/assets/architecture.svg" alt="vibecarbon deploy fans out to three scenarios: compose (one server), k8s (k3s cluster, autoscaling workers), and k8s-ha (multi-region, one-command failover), all landing on Hetzner, DigitalOcean, Linode, Vultr, or Scaleway" width="880" />
</p>

---

## Documentation

| Document | Description |
|----------|-------------|
| [Technical Guide](./docs/technical.md) | Architecture, code examples, API patterns, scripts |
| [Design Guide](./docs/design.md) | Brand identity, visual design, UX principles |
| [Test Suite](./docs/tests.md) | Test types, coverage, and how to run them |

### Deployment Guides

| Guide | Best For |
|-------|----------|
| [Hetzner Cloud](./docs/deploy-hetzner.md) | Cloud servers and Object Storage, with European (EU data residency) and US regions |
| [DigitalOcean](./docs/deploy-digitalocean.md) | Droplets and Spaces, with Americas, Europe, and Asia-Pacific regions |
| [Kubernetes README](./carbon/k8s/README.md) | K8s autoscaling, worker bounds configuration, HA cluster setup |

DigitalOcean and Linode are fully supported for `compose`, `k8s`, and `k8s-ha` with the same CLI, the same lifecycle, and the same e2e gate as Hetzner. Kubernetes on Linode runs in every region except Newark (us-east) and Atlanta (us-southeast). Vultr and Scaleway are supported for `compose`, with the same CLI and e2e gate. The remaining modes aren't built for them yet, though Compose HA is available on every provider regardless (see Architecture above).

### Integration Guides

| Guide | Description |
|-------|-------------|
| [Observability](./docs/integrations/observability.md) | Prometheus, Grafana, Loki |

---

## Performance

Real numbers, not estimates. Every cell is wall-clock time for the CLI command it names, from the latest fully-green CI run of that provider against real cloud infrastructure. Measured from GitHub-hosted runners; methodology in [docs/tests.md](./docs/tests.md).

The rows are every provider and deploy scenario the CLI supports. An absent row means that scenario is not offered on that provider yet; _pending_ means it ships but has no measured CI baseline yet. The numbers refresh automatically from each provider's next green CI run.

<!-- BEGIN:perf-table -->
| Provider | Scenario | Cold `deploy` | Warm `deploy` | `backup` | `restore` | `scale` | `destroy` | `failover` |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| Hetzner Cloud | `compose` | 1m 52s | 25.8s | 4.2s | 2m 36s | 2m 36s | 22.7s | — |
| | `compose-ha` | 2m 49s | 50.1s | 5.7s | 2m 51s | 3m 8s | 27.3s | 43.8s |
| | `k8s` | 2m 45s | 11.1s | 24.8s | 2m 0s | 3m 2s | 1m 46s | — |
| | `k8s-ha` | 4m 14s | 26.8s | 23.7s | 2m 30s | 5m 0s | 2m 0s | 3m 39s |
| DigitalOcean | `compose` | 2m 31s | 46.3s | 5.7s | 2m 49s | 2m 24s | 30.9s | — |
| | `compose-ha` | 3m 38s | 56.5s | 4.5s | 5m 8s | 3m 2s | 29.3s | 34.8s |
| | `k8s` | 3m 13s | 8.1s | 43.5s | 1m 28s | 2m 56s | 2m 7s | — |
| | `k8s-ha` | 4m 10s | 25.9s | 1m 0s | 2m 9s | 6m 7s | 2m 52s | 3m 16s |
| Linode | `compose` | 2m 41s | 26.4s | 7.2s | 3m 53s | 4m 0s | 15.3s | — |
| | `compose-ha` | 3m 32s | 36.0s | 5.0s | 4m 8s | 3m 17s | 24.8s | 1m 18s |
| | `k8s` | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ |
| | `k8s-ha` | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ | _pending_ |
| Vultr | `compose` | 2m 33s | 39.5s | 5.1s | 4m 42s | 3m 7s | 18.0s | — |
| | `compose-ha` | 3m 34s | 48.8s | 4.9s | 11m 18s | 3m 40s | 23.1s | 1m 30s |
| Scaleway | `compose` | 2m 32s | 49.8s | 5.5s | 2m 57s | 3m 2s | 29.7s | — |
| | `compose-ha` | 5m 18s | 1m 32s | 6.7s | 4m 23s | 5m 10s | 41.2s | 1m 3s |

_Latest green CI runs: Hetzner Cloud `1904abc` (2026-11-07) · DigitalOcean `a2c67c1` (2026-11-07) · Linode `1720818` (2026-11-07) · Vultr `1870cad` (2026-11-07) · Scaleway `109d04a` (2026-11-12) · GitHub-hosted runner · methodology: [docs/tests.md](./docs/tests.md)._
<!-- END:perf-table -->

`k8s-ha` (pilot-light multi-region with one-command failover) runs on Hetzner, DigitalOcean, and Linode today.

---

## What it costs to run

<!-- BEGIN:cost-grid -->
You pay your cloud provider directly, and vibecarbon starts every new project on the cheapest servers you can order today that fit the measured load. This is the monthly bill for one environment at those default sizes.

**What each mode runs**

| Mode | Servers | Peak RAM used per server |
|---|---|---|
| compose | 1 | 1.10 GB |
| compose-ha | 2 (primary + standby in a second location) | 1.25 GB |
| k8s | 3 (master, database, worker) | 1.49 GB master, 0.64 GB database, 1.05 GB worker |
| k8s-ha | 5 (3 primary + 2 standby in a second location) | 1.56 GB master, 0.66 GB database |

**Monthly cost per environment**

| Provider | compose | compose-ha | k8s | k8s-ha |
|---|---|---|---|---|
| Hetzner (USD account) | $23.59 (nbg1) | $47.18 (nbg1 + fsn1) | $65.61 (nbg1) | $107.64 (nbg1 + fsn1) |
| DigitalOcean | $24 (nyc3) | $48 (nyc3 + tor1) | $61 (nyc3) | $98 (nyc3 + tor1) |
| Vultr | $20 (ewr) | $40 (ewr + ord) | not yet | not yet |
| Linode | $24 (us-iad) | $48 (us-iad + us-ord) | $65.96 (us-iad) | $107.93 (us-iad + us-ord) |
| Scaleway | €21.84 (fr-par-1) | €43.68 (fr-par-1 + nl-ams-1) | not yet | not yet |

Plus object storage for backups and uploads, billed once per provider account and shared by every project on it: Hetzner $7.99 (this USD account; €6.49 on EUR accounts), DigitalOcean $5, Vultr $18, Linode $5, Scaleway usage-based (cents at this size).

<sub>Prices and availability from each provider's API on 22 October 2026, excluding VAT. Each server has at least twice its measured peak RAM, and compose servers never go below 4 GB. Totals include billed public IPv4 (Hetzner, Scaleway), the k8s ingress IP and database volume, and Scaleway's 40 GB root volume. The region in a cell is where a new project deploys by default, the cheapest location on the provider's home continent; HA standbys sit in a second location on the same continent, and both sides of an HA pair run the same class of server whenever both locations sell one. Peak RAM was measured 20 October 2026 on Hetzner with the observability add-on running, so a default install uses less. Hetzner bills this account in USD; EUR accounts are billed in EUR. Hetzner's cheaper cx23 comes and goes from stock in the EU, and new deploys pick it automatically when it is in stock.</sub>
<!-- END:cost-grid -->

---

## License

The CLI, template and carbon-autoscaler image are MIT licensed, see [LICENSE](./LICENSE). The Postgres and Node runtime images package upstream software under those projects' own licenses. The Vibecarbon name and logo are covered by [TRADEMARK.md](./TRADEMARK.md).

---

## Support

- Discord: [join the community](https://discord.gg/up8Z9sX6M6) for help, showcase, and announcements
- GitHub Issues: [Report bugs or request features](https://github.com/hyperformant/vibecarbon/issues)
- GitHub: [github.com/hyperformant/vibecarbon](https://github.com/hyperformant/vibecarbon)

