vibld

---

vibld turns plain words into a conventional React and TypeScript project. It picks a direction with you, writes the design down, builds in bounded steps, checks its own work against what it wrote, proves the result compiles, and hands you code you can read line by line, run anywhere and take with you.

[!NOTE] vibld is early. The hosted service is a public beta that anyone can sign up for, and the status section says plainly what works and what does not yet.

Contents

• Three ways to use it
• How it works
• What it has built
• Designed, not templated
• Features
• Status
• Quick start
• Architecture
• Running it yourself
• Documentation
• Contributing
• License

Three ways to use it

	☁️ Hosted	⌨️ Your key, your terminal	🛠️ Self-hosted
What you get	The whole builder: chat, previews, projects, sharing, GitHub and publishing.	The same bounded build, from the command line, writing a project to disk.	Your own copy of the hosted service on your Cloudflare account.
What you need	A browser. Sign up.	Node 24, pnpm and one Anthropic, OpenAI or DeepSeek key.	Cloudflare (Workers Paid for sandbox previews and publishing) and a model key; Clerk, Stripe and a GitHub App only if you want them.
What it costs	Free plan, or a paid plan with more model spend. Pricing.	What your provider bills. The weekly proof run costs about $0.15 to $0.31 on DeepSeek.	Your Cloudflare and provider bills.
Where to start	Getting started	Quick start	Self-hosting (documented and checked by the project, not yet by anyone else)

How it works

Step	What happens
1. Say what you want	Plain words. It may answer, or ask one or two questions first; when you say go, your answers become a full brief. Style, a reference page, your own images and video, and standing instructions sit in one row under the message box.
2. Pick a direction	Choose one of 24 style presets, with suggestions for the mood your request names, or ask for three directions to compare before anything is built.
3. It writes the spec down	The direction becomes DESIGN.md: colors, type, breakpoints and motion the build has to honor, kept in the project.
4. It builds in bounded steps	A plan, then files in small groups, each with a ceiling on tokens and time. A draft of the page shows while the first build runs, and a build keeps going if you close the tab.
5. It checks its own work	Design checks read the files against the spec (colors, type, breakpoints, alt text, contrast, motion, copy). Then a real production build: if it fails, one repair patch, then the build again.
6. Look at it live	Run a live preview: the real dev server in a private sandbox, which picks up each new revision in place. Share it by link until you revoke it.
7. Ship it, or take the code	Download a .zip, create or push to a GitHub repository for this project, or publish it at <name>.vibld-preview.dev. Unpublishing is one step too.

These screenshots are from a local checkout, which uses a deterministic fake provider instead of a model (tagged vibld · fake), so the files shown are fixture output.

What it has built

Real builds from the evaluation suite, published exactly as the model wrote them, with no hand edits. Each links to its live copy; the prompt, the run and anything worth knowing are on vibld.com/examples, and the source is in examples/generated.

Two hand-built starter templates ship alongside, each under its own MIT license: templates/marketing, a plain prerendered marketing site, and templates/luminous, a product site with a cursor-reactive glow, dressed for an invented SaaS called Emberline.

Designed, not templated

Every build starts from a written design, not a theme. There are 24 style presets, 16 surface treatments from Editorial and Brutalism to Liquid glass, and 8 complete color systems. Each carries mood tags (luxe, calm, technical, organic, playful, brutal), so the picker can suggest the ones your request describes.

Ask for an aurora, a starfield, a smoky gradient or any "animated background", and the build imports one of four backgrounds written once and tested, rather than improvising a canvas loop. Each takes the project's own color tokens, caps its pixel ratio, pauses off screen and holds still for anyone who asks for reduced motion.

Features

Building

• A conversation, not a form: the agent answers questions, asks its own when a request is thin, and builds when you say so. Follow-ups ("make the hero navy") change the project rather than starting over.
• Model providers behind one contract in packages/ai: Anthropic, OpenAI and DeepSeek adapters, chosen per run.
• Bounded, multi-step builds: a plan, then files in groups, each with its own ceiling on tokens and time, that keep running when you close the tab.
• Three directions to compare before the first build, 24 style presets with mood suggestions, a reference page whose text, colors, fonts and spacing the spec measures, and your own uploaded images and video.
• Four tested animated backgrounds a build imports when a request asks for motion.
• Templates to start from, by category (Websites, Apps, App screens, then subcategories such as Ecommerce or Portfolio), with the 1,300+ gallery styles among them (vibld.com/templates).
• What a build is expected to cost on the chosen model, shown beside Send before you send it, from the last 30 days of builds on that model, or the most a build can cost ("Up to") until it has enough of them; a project's first build also adds the most its draft can cost.

Checking

• Design checks against the project's own DESIGN.md: palette, type, breakpoints, alt text, labels, contrast, reduced motion, media, copy and canvas performance.
• A verification build of every result, with one repair patch when it fails, and a badge that says which: checking, fixing, does not build or not checked.
• A spend ceiling reserved before each run starts, not counted after it finishes.

Previewing, sharing and shipping

• A live preview in a private sandboxed container running the real dev server, updated in place as the project changes, with revocable share links (apps/preview).
• On a copy without Containers, the same preview bundled in the viewer's browser, in a frame with no origin of its own (apps/web/src/browser-preview).
• Projects: save, rename, archive, duplicate and delete, a read-only share link, and Remix for anyone you send it to.
• One Ship menu: download a .zip, create or push to a GitHub repository for each project, or publish to <name>.vibld-preview.dev with safe default security headers (apps/publish).
• A History tab: the newest 100 checkpoints, any of which can be restored in one step without deleting the others.
• A Runs tab: every run's model, tokens, cost and why it stopped.

Accounts and operations

• Sign-in with Clerk, or on a copy of your own with an owner password or Cloudflare Access; projects in Cloudflare D1, R2 and a per-user Durable Object; builds as Cloudflare Workflows.
• Plans and model-spend credit with Stripe, with opt-in auto-reload of the top-up and opt-in Start Build when Free drops below $1, referrals, an access gate that is invite-only unless a deployment opens it, an admin panel with credit grants, bans and an audit log, and operator takedown for abuse reports.
• An evaluation suite (packages/eval) and a model bakeoff, so model choices are measured, not guessed.

Status

What runs today. Everything above, deployed at app.vibld.com as a public beta. Paid plans are live; the Free plan builds with GPT-6 Luna, with a one-time $0.20 trial and then $1.00 of model spend a month once it saves a card no other account saved first (or buys a plan or top-up), which is not charged unless you turn on auto-reload or Start Build. From a checkout, pnpm generate --build builds a real project with your own provider key, and a weekly workflow proves that from a clean clone.

What does not exist yet.

• Repository search over an existing codebase (internal issue 12).
• A bakeoff result strong enough to recommend one model over another. The harness exists and has run; the evidence does not settle it yet.
• Sandbox output in the builder's own panes. The console shows generation events, and Problems shows the design checks and the verification build, not the install, build and type errors from a live preview.
• A self-hosting path validated outside the project. A workflow deploys a separately named copy from the docs, checks it refuses a signed-out caller, then signs in with the owner's password and builds one site on it with a real model, on Cloudflare and under Docker. Nobody outside the project has deployed their own copy yet.
• The builder's interface against a real model from pnpm dev, which runs the fake provider. Its model path needs sign-in, D1, R2 and a Workflow, which a Cloudflare deployment has and so does the Docker setup, with a key or a local model.

What to be careful of. It is a beta, not a place for work you cannot afford to lose. Very little of it has been used by anyone other than its author, which is a different kind of risk from a missing feature and not one a feature list shows.

The accepted decisions, the architecture decision records and the roadmap say where it is going and why.

Quick start

You need Node.js 24 (the LTS release CI uses; 22.15 or newer also works) and pnpm. The version is pinned in package.json, and corepack enable provides it.

git clone https://github.com/vibld/vibld.git
cd vibld
pnpm install --frozen-lockfile

Generate a real project with your own key

One provider key is all this needs: no account, database or Cloudflare. It runs the same bounded build as app.vibld.com, prints each step and what it cost in tokens, and writes the project it built.

export DEEPSEEK_API_KEY=...   # or ANTHROPIC_API_KEY, or OPENAI_API_KEY

pnpm generate "A one-page site for a neighbourhood bakery, with opening hours and a menu" --out ./my-site --build

cd my-site
npm run dev                   # the generated project, with no vibld dependency

Option	What it does
--out <dir>	Where the project is written, relative to where you ran the command.
--build	Installs and builds the result with npm and, when it does not build, asks for one repair with the compiler's output. The build gets no credential from your environment.
--style <id>	One of the style presets, by id: editorial, brutalism, liquidGlass, bentoGrid, warmPaper, cinematic and the rest in style-presets.ts.
--base <dir>	Makes the prompt a follow-up to a project already on disk.
VIBLD_MODEL=<id>	Another model from the catalog. With one key set, that provider's default answers: deepseek-flash, gpt-5.6-terra or claude-opus-5-5.
VIBLD_PROVIDER=local	A model on your own machine instead of a key, with VIBLD_LOCAL_BASE_URL and VIBLD_LOCAL_MODEL set (Local models).

The calls are billed to your key. The weekly proof run, a one-page bakery site on DeepSeek's default model, has taken 7 to 17 minutes and cost $0.15 to $0.31, most of it the model's reasoning. A larger request or a costlier model costs more: Claude Opus 5.5, Anthropic's default here, costs many times what DeepSeek Flash does. packages/ai/README.md has the details.

Run the builder locally

pnpm --filter @vibld/web dev   # the builder, at http://localhost:5173

Locally, the builder runs with no sign-in and a deterministic fake provider, so you can go through the whole flow at no cost and no model is called. apps/web/README.md covers deploying it with a real model provider, sign-in, the sandbox and the rest.

Before you open a pull request

pnpm format:check   # Prettier
pnpm check:style    # house style, including no em-dashes
pnpm typecheck      # every workspace, through Turborepo
pnpm test
pnpm test:scripts   # the repository scripts
pnpm build          # every app's production build

Architecture

flowchart LR
  user([You]) --> web["apps/web<br/>builder SPA + Worker"]
  web -->|plan, stage, check| ai["packages/ai<br/>model adapters"]
  ai --> models[("Anthropic · OpenAI · DeepSeek")]
  web --> core["packages/core<br/>contracts, state machine,<br/>run budget"]
  web --> state[("D1 · R2 · Durable Object<br/>· Workflow")]
  web -->|run in sandbox| preview["apps/preview<br/>sandbox Worker + containers"]
  web -->|publish| publish["apps/publish<br/>published sites"]
  web -->|branch + pull request| gh[(Your GitHub repo)]
  web -->|export| zip[(.zip)]

Path	What it is
apps/web	The builder: a React single-page app and the Cloudflare Worker behind it.
apps/preview	The sandbox Worker that installs and runs a generated project in a container for private previews.
apps/publish	Serves published sites on *.vibld-preview.dev.
apps/marketing	vibld.com, built with the same stack generated sites use.
packages/core	Generation contracts, the state machine and the run budget. No provider code.
packages/ai	Model adapters, prompts, style presets and the design checks.
packages/eval	The evaluation cases and the checks that decide whether a generated project is accepted.
packages/brand	The palette and mark, shared by every surface.
packages/security-headers	Response headers for vibld.com and app.vibld.com.

VIBLD.md is the product and architecture charter behind all of it.

Running it yourself

Self-hosting is possible, and still needs validation outside the project: a workflow deploys a separately named copy from the docs, signs in to it and builds one site on it, on Cloudflare and under Docker, but nobody else has deployed their own copy yet. A deployment needs:

• Cloudflare, for three Workers (the builder, the sandbox and the publish service) plus D1, R2, a Durable Object and a Workflow behind the builder. Publishing, and live previews in a sandbox, run generated code in Containers, which need the Workers Paid plan, and building the sandbox image needs Docker. Without Containers, the Preview pane bundles the project in the viewer's browser instead (esbuild-wasm, packages from esm.sh, Tailwind compiled in the browser).
• A model provider API key. Without one, generation refuses rather than degrading. The builder's configuration ships VIBLD_MODEL as gpt-6-sol: set it to a model your key serves. A copy that names a model none of its keys serves refuses a build that does not pick a model, and says why (D91); a model picked in the builder that its keys serve still runs. scripts/self-host.mjs, Docker and Render leave it unset, so they use the model your key serves.
• A way to sign in, one of three: an owner password (VIBLD_AUTH=owner, one person), Cloudflare Access in front of the builder (VIBLD_AUTH=access, free for up to 50 users), or Clerk (for sign-ups from the public, as app.vibld.com uses). There is no mode without sign-in, because the endpoints spend money.
• An open door. A deployment is invite-only until VIBLD_ACCESS_MODE is open: before that, only the verified emails in VIBLD_PLATFORM_ADMINS and the people they invite get in, so list your own. The owner of an owner-password copy is always let in. Under Clerk, its session token has to carry email and email_verified for that match to work.
• Your own names. The Worker names, database, bucket, Workflow, routes and Clerk domain in the wrangler.jsonc files are vibld's. node scripts/self-host.mjs <settings.json> writes a wrangler.self-host.jsonc beside each with all of them derived from a prefix of yours, and refuses to write one that still names vibld's (Deploying).
• Stripe only if you intend to charge anybody, a GitHub App of your own only if you want each project in a GitHub repository (Pushing to GitHub), and Resend only for email. Each optional piece left unset reports itself unavailable rather than running without its check.

Run it with Docker

The whole builder also runs on one machine under Docker, with no Cloudflare account (docs/decisions.md D126). It needs Docker with Compose, a model key or a local model, and a password to sign in with.

cp .env.example .env    # set VIBLD_OWNER_PASSWORD and a model key or a local model
docker compose up --build

Then open http://localhost:8787 and sign in with that password. Previews open at http://<...>.localhost:8788 and published sites at http://<slug>.localhost:8789; browsers send any *.localhost name to this machine.

• What runs. The builder, previews and publishing are three Workers under workerd (wrangler dev), with their database, files, Durable Objects and Workflow in the vibld-data volume. Secrets they share are made on first start and kept there.
• Previews run on your Docker (D137). Each preview's sandbox is its own container, started through the Docker socket the compose file mounts, the same way it runs on Cloudflare. Anything in control of the vibld container can control your Docker.
• Host networking. The vibld container uses the host's network, so the sandboxes it starts can reach it and it can reach them. On Docker Desktop (macOS, Windows), turn on host networking first: Settings, Resources, Network, "Enable host networking".
• Sign-in is the owner's password (VIBLD_AUTH=owner); Clerk and Cloudflare Access are services outside the box.
• Keys can be set in .env or later on the admin page under Provider keys. A local model is set in .env.
• GitHub works with a GitHub App of your own, its five values set in .env.
• Not under Docker: the nightly jobs (scheduled cleanups and the billing pass), which wrangler dev does not run on a schedule; and Stripe and email, whose keys the Docker setup does not pass on.

Local models

A copy can build with a model running on your own machine instead of, or as well as, a provider key (docs/decisions.md D124). Anything that answers OpenAI's chat completions API works: Ollama, LM Studio or llama.cpp's server. Set two settings, in .env under Docker or as Worker variables on Cloudflare:

Setting	What it is
VIBLD_LOCAL_BASE_URL	The server's address, ending in /v1: http://localhost:11434/v1 for Ollama, http://localhost:1234/v1 for LM Studio, http://localhost:8080/v1 for llama.cpp.
VIBLD_LOCAL_MODEL	The model's name on that server, as it lists it: qwen2.5-coder:7b, for example.
VIBLD_LOCAL_API_KEY	Only for a server started with an API key.

The builder then offers it as "Local: ", and with no provider key set it is the default. It costs nothing per token, so it does not draw on anybody's allowance. pnpm generate uses it too, with VIBLD_PROVIDER=local.

• Give it a context window of 32,768 tokens or more. Ollama's default is smaller, and Ollama cuts a longer prompt without saying so. When it cuts a fifth or more, vibld notices and stops the build with a message saying so; a smaller cut it cannot tell from the difference between tokenizers. Start Ollama with OLLAMA_CONTEXT_LENGTH=32768, or set the context length in LM Studio's model settings.
• Size matters more than anything else. A model too small for the work writes files that do not build, or replies that are not the shape asked for, and vibld says so plainly. On a 4-core CPU with no GPU, Qwen2.5 Coder 1.5B planned and wrote a one-page bakery site in 6 minutes, and most of its files were a single line of markup with no imports, which does not build.
• Speed is your machine's. Each step is sized for a model that writes about 12 tokens a second, and is given twice the time that needs. A slower machine can run out of time on a large step.
• Under Docker, vibld uses your machine's network, so localhost in these settings is your machine. On Cloudflare, the Worker can only reach an address on the public internet, so the server has to be reachable from there.

Deploy to a container host

A host that runs one container on one port, such as Render, can run the same image with VIBLD_SANDBOX=off (docs/decisions.md D141). render.yaml sets it up: Render asks for your password and a model key, and keeps your projects on a 5 GB disk at /data. A disk needs a paid Render instance type.

• The builder runs alone. Such a host gives no Docker socket, so there is no sandbox: previews bundle in the viewer's browser (as on Cloudflare without Containers), builds are not checked in a sandbox, and publishing reports itself unavailable.
• It listens on PORT, which the host sets.
• Checked so far: CI starts the image this way and signs in. Nobody has deployed it to Render yet.

Run it on a server

On a server of your own on the internet, vibld runs as it does under Docker, sandbox previews and publishing included, with a proxy in front that ends TLS (docs/decisions.md D141). infrastructure/vps/cloud-init.yaml sets up a new Ubuntu 24.04 server in one paste. A server with 4 GB of memory or more is a reasonable start: it builds the image and runs each preview's sandbox.

1. Two domains. One for the builder, such as build.example.com, and one of its own for previews and published sites, such as example-preview.dev. Previews run code nobody has reviewed, so they never share the builder's domain (L8). The previews' domain needs its DNS on Cloudflare, which issues its wildcard certificate.
2. A Cloudflare token at https://dash.cloudflare.com/profile/api-tokens: "Create Custom Token", permissions Zone / DNS / Edit and Zone / Zone / Read, zone resources: the previews' domain.
3. The server. Fill in the settings at the top of cloud-init.yaml and paste the whole file as user data: https://cloud.digitalocean.com/droplets/new ("Advanced options", "Add Initialization scripts") or https://console.hetzner.cloud ("Cloud config").
4. DNS, with the server's address: an A record for the builder's domain, and A records for the previews' domain and *. the previews' domain (on Cloudflare, "DNS only", not proxied).

Then open https://<builder domain> and sign in with the password you set. The first start builds the image, which takes a few minutes.

• Only 22, 80 and 443 are open. The Workers listen on 127.0.0.1 behind the proxy, and firewall.sh keeps the internet out of the preview containers and keeps them away from the cloud's metadata service, which holds the user data and the keys in it.
• Updating: cd /opt/vibld && git pull && docker compose -f docker-compose.yml -f infrastructure/vps/compose.yml up --build --detach.
• Checked so far: CI starts it behind the proxy with made-up domains, signs in through the proxy and checks the Workers' ports are closed. Nobody has run cloud-init.yaml on a real server yet.

Pushing to GitHub

A copy creates and pushes to a GitHub repository for each project through a GitHub App of its own, the way app.vibld.com does through vibld's: each checkpoint becomes a branch vibld/<revision> and a pull request. It works the same on Cloudflare, under Docker, on Render and on a server. <address> below is where your copy's builder is, such as http://localhost:8787 under Docker.

1. Create the App at https://github.com/settings/apps/new:
   • Homepage URL: <address>.
   • Callback URL: <address>/api/github/callback, and tick Request user authorization (OAuth) during installation.
   • Webhook: Active, Webhook URL <address>/api/github/webhook, Secret a long random value. Untick Active when GitHub cannot reach your copy, as under Docker on your own machine; a merged pull request is then not reported back to the builder.
   • Repository permissions: Contents and Pull requests, both Read and write. Add Administration: Read and write for "Create a new repository"; without it, only existing repositories can be picked.
   • Subscribe to events: Pull request.
   • Where can this GitHub App be installed: Only on this account, or Any account when other people sign in to your copy.
2. On the App's page, copy the App ID and Client ID, then Generate a new client secret and Generate a private key (a .pem file that downloads once).
3. Give your copy the five values:

Setting	Value
VIBLD_GITHUB_APP_ID	App ID
VIBLD_GITHUB_PRIVATE_KEY	The whole .pem, BEGIN and END lines included
VIBLD_GITHUB_CLIENT_ID	Client ID
VIBLD_GITHUB_CLIENT_SECRET	The client secret
VIBLD_GITHUB_WEBHOOK_SECRET	The webhook secret, if the webhook is on

On Cloudflare, each is a Worker secret: npx wrangler secret put <setting> -c wrangler.self-host.jsonc in apps/web. Under Docker or on a server, they go in .env, the key on one line in double quotes with \n for each line break (awk 'NF {printf "%s\\n", $0}' key.pem prints it that way). On Render, they are on the service's Environment page.

Then, in the builder, open Ship; under Push to GitHub, pick "Create a new repository" or "Use an existing repository". When the App is not installed where the repository is, the builder offers your App's own installation page, which it looks up from the App ID and key.

Read next: what self-hosting involves, every setting and secret, deploying your own copy and hosted or self-hosted. The exact commands are in apps/web/README.md, apps/preview/README.md and apps/publish/README.md, beside the code they deploy. The workflows that deploy vibld's own hosted service run only in the maintainers' working repository, since a copy has none of their secrets.

Documentation

If you want to	Read
Use the hosted builder	Getting started · The builder · Running your project · Taking your code · Credits and plans
Build from your terminal with your own key	Quick start · packages/ai/README.md
Run your own copy	Self-hosting · Configuration · Deploying · apps/web/README.md
Understand why it is built this way	VIBLD.md · Decisions · ADRs · Roadmap
Change it	CONTRIBUTING.md · ·

Contributing

Issues, discussions and pull requests are welcome. Start with CONTRIBUTING.md, which also explains how a change reaches this repository, and the code of conduct. Questions and ideas go to Discussions; bugs go to issues.

Found a vulnerability? Report it privately through SECURITY.md, never in a public issue.

License

Built by Chris Brock (@cbrock84), the lead maintainer (GOVERNANCE.md); CITATION.cff says how to cite it.

The core is licensed under Apache-2.0; see also NOTICE. The starter templates in templates/marketing and templates/luminous each carry their own MIT LICENSE at their own boundary, which does not relicense the core (ADR-0008). THIRD_PARTY_NOTICES.md lists the projects whose material is adapted here, with the license text each one publishes.