drobek

![The drobek pixel mascot](./docs/assets/drobek.svg)

# drobek

[![CI](https://github.com/freema/drobek/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/freema/drobek/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/freema/drobek)](https://github.com/freema/drobek/releases/latest)
[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](./LICENSE)
[![Image](https://img.shields.io/badge/image-ghcr.io%2Ffreema%2Fdrobek-2496ed)](https://github.com/freema/drobek/pkgs/container/drobek)

> Open-source vibe coding hosting: your AI agent builds the web app, drobek
> compiles, previews and publishes it.

Bring Claude, Claude Code, Cursor or Codex. Your agent connects over MCP,
writes the app directly into a workspace and gets compile feedback and a
live preview. You decide when to publish. Platform modules supply sign-in,
data, forms, e-mail, uploads, external APIs and scheduled imports; a
dashboard gives you control over the app, its users and its secrets.
Built something as a Claude artifact? Your agent moves its files over
unchanged and hands you a preview.

An open-source, self-hostable alternative to Lovable, Bolt.new and v0 for
people who already have an agent: drobek has no chat of its own, the agent
you use does the building, and drobek compiles, versions, previews and
hosts what it writes.

**[Try drobek.app](https://drobek.app/login)** ·
**[Self-host](#self-host-quickstart)** ·
**[Gallery](https://www.drobek.app/gallery)** ·
**[Docs](https://www.drobek.app/docs)**

MCP Registry name: [`io.github.freema/drobek`](./server.json). The hosted
Streamable HTTP endpoint is `https://drobek.app/mcp` and uses OAuth 2.1.

## Choose where to run it

| | Get started |
| --- | --- |
| **drobek.app** | The maintainer's hosted instance. [Sign in](https://drobek.app/login) and [connect your agent](https://drobek.app/build-with-your-agent). |
| **Your own server** | Run the same public image with Postgres, Redis and Caddy. Follow the [self-host quickstart](#self-host-quickstart), then connect your agent to your server's `/mcp` endpoint. |

The core is **AGPL-3.0**. Building, testing and self-hosting need no access
to the private repository that operates drobek.app. The
[agent plugins](https://github.com/freema/drobek-plugin) are **MIT** and can
connect to either instance.

## See what people build

- [Drobek Tycoon](https://drobek-tycoon.drobek.app/) — a playable hosting-company simulator with three levels.
- [Pokédex](https://pokedex.drobek.app/) — PokéAPI search and stats through drobek's proxy module, with a live request log.
- [Pixel Wall](https://pixel-zed.drobek.app/) — a shared 64 × 40 canvas backed by auth, data and other platform modules.
- [Pixel Crumbs](https://pixel-crumbs.drobek.app/) — a browser pixel-art and animation editor.
- [Drobek Skok](https://drobek-skok.drobek.app/) — a pixel platformer with a leaderboard.
- [Pekárna Drobek](https://pek-rna-drobek.drobek.app/) — a small bakery's demo website.

These are public apps on drobek.app. [Browse the gallery](https://www.drobek.app/gallery)
for more examples.

[![Drobek Tycoon running on drobek](./docs/assets/drobek-tycoon.jpg)](https://drobek-tycoon.drobek.app/)

## Build your first app

1. Choose an instance above and [connect your agent](#connect-your-agent).
2. Ask for a small app, for example:

   ```text
   Build a shift planner for our team on drobek.
   Let people sign in and see their own shifts.
   Give me a preview to try before publishing.
   ```

3. Open the preview, ask for changes, then ask the agent to publish when ready.

Apps run in the browser. Their backend comes from installed platform
modules; arbitrary app server code and per-app `npm install` are outside
the execution model. For your own backend integration,
[write a platform module](#extend-drobek-write-a-module).

## The loop

1. Connect drobek to your agent (an MCP server with OAuth — you approve it in
   the browser).
2. Ask for an app: *"a shift planner for our warehouse"*. The agent calls
   `create_app` and gets a compiling starter plus a briefing of the rules.
3. It calls `write_files`. drobek compiles the files in-process with esbuild
   and returns the compile errors **in the same response**; the agent fixes
   them and writes again. Every write is an immutable version.
4. Each successful compile is live at once on the app's preview host,
   `https://<slug>--preview.<APPS_DOMAIN>` — the agent hands you the link.
5. When you are happy, the agent calls `publish` and the version goes live on
   `https://<slug>.<APPS_DOMAIN>` (or your own domain). Publishing an older
   version is the rollback.

Why it is built this way:

- **The server never executes app code.** It compiles and serves; the result
  runs only in browsers. No sandbox per app, no `npm install`, no server-side
  code of the agent's.
- **Secrets never pass through the agent.** The app owner sets them in the
  dashboard; modules use them server-side.
- **Every app is its own origin** (`<slug>.<APPS_DOMAIN>`), separate from the
  dashboard's.
- **One process, one image** (`ghcr.io/freema/drobek`) + Postgres + Redis
  (+ Caddy for TLS). It runs on an ordinary small server.

## Core concepts

**Agent plugins and platform modules do different jobs.** A plugin teaches
your agent how to build on drobek. A module runs on the drobek server and
adds backend capabilities for apps. Installing a plugin does not install
server modules. See the [repository and compatibility map](./docs/ECOSYSTEM.md).

- **Workspace** — people with roles (workspace-admin / editor / viewer).
- **App** — a globally unique slug, owned by a workspace. Its hosts:
  `<slug>.<APPS_DOMAIN>` (published), `<slug>--preview.<APPS_DOMAIN>` (the
  newest version that compiled), `<slug>--v<N>.<APPS_DOMAIN>` (exactly version
  N), plus verified custom domains.
- **Version** — an immutable, numbered snapshot of the app's sources and
  compiled output. Publishing moves one pointer.
- **Platform modules** — the only backend an app gets: routes under
  `/__drobek/v1/<name>` on the app's host, `drobek.<name>` in the browser SDK,
  a per-app config the agent proposes and the owner confirms when it is risky,
  a skill the agent reads. Built in (`modules/`, enabled with
  `DROBEK_MODULES`):
  - **`auth`** — the app's users sign in with an e-mailed code (allowlist,
    admins, `<LoginGate>`, sessions the owner can revoke);
  - **`data`** — collections of records with per-operation rules
    (`public` / `user` / `owner` / `admin`), JSON Schema, CSV;
  - **`forms`** — `<Form>` submissions stored and e-mailed to the owners, with
    bot protection;
  - **`email`** — notifications to the app's owners (never to arbitrary
    addresses), per-app and server-wide budgets;
  - **`files`** — end-user uploads with types sniffed from the bytes and a
    per-app quota;
  - **`proxy`** — calls to external APIs with the secret injected
    server-side, behind an SSRF guard.

  Operators can add their own modules against the public contract:
  `npm create drobek-module@latest <name>` scaffolds one against the npm
  packages `@freema/drobek-modules` + `@freema/drobek-sdk` (imported as
  `@drobek/modules` / `@drobek/sdk` through npm aliases) —
  [`docs/MODULES.md` → Writing a module](./docs/MODULES.md#writing-a-module).

## Self-host quickstart

<!-- quickstart:start -->
What you need:

- a server with a public IPv4 (and/or IPv6), **linux/amd64** (there is no ARM
  image in v1), ports **80** and **443** reachable from the internet;
- a domain for the dashboard and a domain for the apps. Create these DNS
  records **before** step 3 (Let's Encrypt checks them):

  | Record | Points at | Example |
  | --- | --- | --- |
  | `A` (and/or `AAAA`) for the dashboard host | the server | `drobek.example.com` |
  | wildcard `A`/`AAAA` `*.<APPS_DOMAIN>` | the server | `*.apps.example.net` |

  A separate registrable domain for the apps (`example.net` next to
  `example.com`) is the safer choice; `apps.<your dashboard domain>` works too.
  No DNS at all (a test box)? Use `DOMAIN=localhost` in step 3 — Caddy's local
  CA (`tls internal`), reachable only from the machine itself.
- an SMTP account (host, port, user, password, a sender address) or a
  Resend API key — sign-in codes go out by e-mail.

Every command runs as root (or prefix `sudo`).

**1. Docker, git and go-task**

```sh
curl -fsSL https://get.docker.com | sh
apt-get install -y git openssl
snap install task --classic
docker compose version     # → Docker Compose version v2.x (or newer)
task --version             # → Task version: v3.x
```

**2. The drobek files** (the compose file, the scripts, the env template —
the image itself comes from GHCR)

```sh
git clone https://github.com/freema/drobek /opt/drobek
cd /opt/drobek
git checkout "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"   # the newest release (skip before the first one)
```

**3. Configuration** — generates every secret, writes `.env.production`
(mode 600), renders `deployments/Caddyfile` with the image's own generator
(no Node on the host):

```sh
DOMAIN=drobek.example.com APPS_DOMAIN=apps.example.net \
TLS_ACME_EMAIL=you@example.com SUPERADMIN_EMAIL=you@example.com \
SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=no-reply@example.com \
EMAIL_FROM=no-reply@example.com \
task selfhost:init
```

Expected output (abridged):

```text
✓ created .env.production from .env.production.example (mode 600)
✓ generated POSTGRES_PASSWORD
✓ generated DROBEK_MASTER_KEY
✓ generated TLS_ASK_TOKEN
✓ dashboard https://drobek.example.com · apps https://<slug>.apps.example.net
✓ TLS mode for the app hosts: on-demand
✓ rendered deployments/Caddyfile (on-demand)
✓ docker compose config: OK
```

Then put the SMTP password in (never on the command line):

```sh
nano .env.production       # SMTP_PASS='…'   (single quotes if it has $, # or spaces)
```

`task selfhost:init` never asks anything and never overwrites a secret; run it
again whene