Vobase

vobase
The app framework built for AI coding agents.
Own every line. Your AI already knows how to build on it.

what you get · get started · code · skills · compare · docs · discord

A full-stack TypeScript framework that gives you auth, database, storage, and jobs in a single process with a single SQLite file. Like a self-hosted Supabase — but you own every line of code. Like Pocketbase — but it's TypeScript you can read and modify.

AI coding agents (Claude Code, Cursor, Codex) understand vobase out of the box. Strict conventions and agent skills mean generated code works on the first try — not the third.

You own the code. You own the data. You own the infrastructure.

what you get

One vobase init and you have a working full-stack app:

Everything runs in one Bun process. No Docker fleet. No external services. bun run dev and you're building.

quick start

bunx @vobase/cli@latest init my-app
cd my-app
bun run dev

Backend on :3000, frontend on :5173. Ships with a dashboard and audit log viewer out of the box.

what you can build

Every module is a self-contained directory: schema, handlers, jobs, pages. No plugins, no marketplace. Just TypeScript you own.

Module starters ship with the CLI: vobase add <module>. Like npx shadcn add button — files get copied, you own the code.

how it works

Vobase makes itself legible to every AI coding tool on the market.

The framework ships with strict conventions and agent skills — domain knowledge packs that teach AI tools how your app works. When you need a new capability:

1. Open your AI tool and describe the requirement
2. The AI reads your existing schema, module conventions, and the relevant skills
3. It generates a complete module — schema, handlers, jobs, pages, tests, seed data
4. You review the diff, run bun run dev, and it works

Skills cover the parts where apps get tricky: money stored as integer cents (never floats), status transitions as explicit state machines (not arbitrary string updates), gap-free business numbers generated inside database transactions (not auto-increment IDs that leave holes).

These conventions are what make AI-generated modules work on the first try.

The thesis: your specs and domain knowledge are the asset. AI tools are the compiler. The compiler improves every quarter. Your skills compound forever.

what a module looks like

Every module declares itself through defineModule(). This convention is what AI tools rely on to generate correct code.

// modules/projects/index.ts
import { defineModule } from '@vobase/core'
import * as schema from './schema'
import { routes } from './handlers'
import { jobs } from './jobs'
import * as pages from './pages'
import seed from './seed'

export default defineModule({
  name: 'projects',
  schema,
  routes,
  jobs,
  pages,
  seed,
})

modules/projects/
  schema.ts           ← Drizzle table definitions
  handlers.ts         ← Hono routes (HTTP API)
  handlers.test.ts    ← colocated tests (bun test)
  jobs.ts             ← background tasks (SQLite-backed, no Redis)
  pages/              ← React pages (list, detail, create)
  seed.ts             ← sample data for dev
  index.ts            ← defineModule()

// modules/projects/schema.ts
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
import { nanoidPrimaryKey } from '@vobase/core'

export const projects = sqliteTable('projects', {
  id: nanoidPrimaryKey(),
  name: text('name').notNull(),
  description: text('description'),
  status: text('status').notNull().default('active'),    // active -> archived -> deleted
  owner_id: text('owner_id').notNull(),
  created_at: integer('created_at', { mode: 'timestamp_ms' })
    .notNull().$defaultFn(() => new Date()),
})

export const tasks = sqliteTable('tasks', {
  id: nanoidPrimaryKey(),
  project_id: text('project_id').references(() => projects.id),
  title: text('title').notNull(),
  status: text('status').notNull().default('todo'),       // todo -> in_progress -> done
  assignee_id: text('assignee_id'),
  priority: integer('priority').notNull().default(0),
})

// modules/projects/handlers.ts
import { Hono } from 'hono'
import { getCtx } from '@vobase/core'
import { projects } from './schema'

export const routes = new Hono()

routes.get('/projects', async (c) => {
  const ctx = getCtx(c)
  return c.json(await ctx.db.select().from(projects))
})

routes.post('/projects', async (c) => {
  const ctx = getCtx(c)
  const body = await c.req.json()

  const project = await ctx.db.insert(projects).values({
    ...body,
    owner_id: ctx.user.id,
  })

  return c.json(project)
})

import { hc } from 'hono/client'
import type { AppType } from '../server'

const client = hc<AppType>('/')
const res = await client.api.projects.$get()
const projects = await res.json()  // fully typed, no codegen

// modules/projects/jobs.ts
import { defineJob } from '@vobase/core'
import { tasks } from './schema'
import { eq } from 'drizzle-orm'

export const sendReminder = defineJob('projects:sendReminder',
  async (data: { taskId: string }) => {
    const task = await db.select().from(tasks)
      .where(eq(tasks.id, data.taskId))
    // send notification, update status, log the action
  }
)

the ctx object

Every HTTP handler gets a context object with runtime capabilities. Current surface:

For jobs, pass dependencies through closures/factories (or import what you need) when calling defineJob(...).

ctx extensions for external integrations

Beyond local capabilities (database, user, scheduler, storage), ctx provides outbound connectivity and inbound event handling:

// vobase.config.ts
export default defineConfig({
  database: './data/vobase.db',
  http: {
    timeout: 10_000,
    retries: 3,
    retryDelay: 500,
    circuitBreaker: { threshold: 5, resetTimeout: 30_000 },
  },
  webhooks: {
    'stripe-events': {
      path: '/webhooks/stripe',
      secret: process.env.STRIPE_WEBHOOK_SECRET,
      handler: 'system:processWebhook',
      signatureHeader: 'stripe-signature',
      dedup: true,
    },
  },
})

Credentials stay in .env. Config declares the shape.

agent skills

Agent skills are the domain knowledge layer. AI tools load skills before generating code. Skill quality determines code quality — these conventions are what separate working modules from broken ones.

Vobase skills use the same format as Claude's native skill system. A skill is a SKILL.md file in .agents/skills/<name>/ with optional bundled resources. Claude (and any compatible AI tool) automatically discovers and loads them through progressive disclosure.

Skills fall into two layers:

core skills — app patterns that apply across every module

These are the rules that prevent the most common mistakes. Every module follows them.

domain skills — industry and vertical-specific logic

These encode domain knowledge for a particular business function, industry, or regulatory environment. Each skill teaches the AI how that domain actually works.

More verticals coming. See vobase add skill --list for what's available. Write your own following the same format.

skill quality — test, measure, refine

Skills are only as good as the code they produce. Vobase uses Claude's skill-creator system to test and improve skills systematically.

The process:

1. Write the skill — SKILL.md with instructions, references, scripts
2. Write test prompts — real requests users would make
3. Define assertions — concrete checks on the generated code
4. Run evals — Claude generates code with the skill loaded, assertions grade the output
5. Benchmark — pass rate, token usage, elapsed time across multiple runs
6. Iterate — rewrite the skill, run again, compare

vobase eval run gap-free-sequences          # run all test prompts against the skill
vobase eval benchmark gap-free-sequences    # 5 runs with variance analysis
vobase eval compare gap-free-sequences      # blind A/B: skill vs no-skill

The comparator runs blind A/B tests — one agent with the skill, one without, a third agent grades which output is better without knowing which had the skill. If the skill doesn't consistently win, it needs rewriting.

vs the alternatives

vs Supabase: Self-hosted Supabase is 10+ Docker containers. RLS policies are hard to reason about. You don't own the backend code. Vobase is one process, one SQLite file, and you own every line — AI agents can read and modify everything.

vs Pocketbase: Pocketbase is a Go binary. You can see the admin UI, but you can't read or modify the internals. When you need custom business logic, you're writing Go plugins or calling external services. Vobase is TypeScript you own — AI agents understand and extend it natively.

vs Rails / Laravel: Great frameworks, but they weren't designed for AI coding agents. Vobase's strict conventions and agent skills mean AI-generated code follows your patterns consistently. Plus: simpler stack (SQLite, no Redis, single process, TypeScript end-to-end).

runtime architecture

One Bun process. One Docker container. One app.

Docker container (--restart=always)
  └── Bun process (PID 1)
        ├── Hono server
        │     ├── /auth/*       → better-auth (sessions, passwords, CSRF)
        │     ├── /api/*        → module handlers (JWT-validated)
        │     ├── /mcp          → MCP server (same process, shared port)
        │     ├── /webhooks/*   → inbound event receiver (signature verified, dedup)
        │     └── /*            → frontend (static, from dist/)
        ├── Drizzle (bun:sqlite, single file in /data/)
        │     └── WAL mode, 5s busy timeout, foreign keys ON
        ├── bunqueue (SQLite-backed job queue, 286K ops/sec)
        ├── Outbound HTTP (typed fetch, retries, circuit breakers)
        └── Audit middleware (all mutations → _audit_log)

tech stack

why sqlite

At 10-200 concurrent users per instance, SQLite with WAL mode outperforms Postgres. PocketBase, Directus, and Strapi all run on it. This isn't a prototype choice — it's an architecture decision.

Backup your entire system:

cp vobase.db backup.db

Clone production for staging:

cp data/vobase.db data/staging.db
DATABASE=./data/staging.db PORT=3001 bunx vobase dev

One file copy. Exact production clone. No database dump/restore, no connection string changes.

Disaster recovery via Litestream — continuous WAL streaming to S3, roughly one second of lag:

litestream restore -o /data/vobase.db -timestamp 2026-03-01T10:00:00Z s3://my-backups/instance-id

Cost: $0.03-0.05/month. Point-in-time recovery to any second.

mcp server

Runs in the same Bun process on the same port. When you connect Claude Code, Codex, Cursor, or any MCP-compatible tool, it sees everything:

The AI sees your exact data model, your existing modules, and the conventions before it writes a single line of code.

deployment

Ship a Docker image. Add Caddy for HTTPS. Done.

# docker-compose.yml
services:
  vobase:
    image: your-registry/my-vobase:latest
    restart: always
    volumes:
      - vobase_data:/data
    ports:
      - "3000:3000"
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"

Litestream wraps the Bun process for continuous backup:

COPY litestream.yml /etc/litestream.yml
ENTRYPOINT ["litestream", "replicate", "-exec", "bun run server.ts"]

Every app gets its own container, its own database, its own backup stream. Physical isolation, not row-level security policies.

cli commands

project structure

my-app/
  .env
  .env.example
  package.json            ← depends on @vobase/core
  drizzle.config.ts
  vobase.config.ts        ← database path, auth, connections, webhooks
  vite.config.ts          ← Vite + TanStack Router + path aliases
  index.html
  server.ts               ← createApp() entry + export type AppType
  AGENTS.md               ← project context and guardrails
  .agents/
    skills/
      integer-money/
        SKILL.md          ← core: all money as integer cents
  modules/
    system/               ← admin dashboard (scaffolded)
      schema.ts
      pages/
        layout.tsx
        list.tsx
        logs.tsx
    index.ts              ← module registry
    projects/             ← example module you add
      index.ts            ← defineModule()
      schema.ts
      handlers.ts
      jobs.ts
      pages/
  src/
    main.tsx
    home.tsx
    root.tsx
    routes.ts             ← generated route definitions
    routeTree.gen.ts      ← generated TanStack route tree
    lib/
      api-client.ts
      auth-client.ts
      utils.ts
    components/
      ui/                 ← shadcn/ui (owned by you)
    shell/
      layout.tsx
      sidebar.tsx
      auth/
        login.tsx
        signup.tsx
    styles/
      app.css
  data/
    vobase.db             ← your entire database
    vobase.db-wal
    vobase.db-shm
    files/                ← optional, created on first upload
    backups/

license

MIT. Own everything.