Zebric is a declarative framework for agent-native applications.

Define your application — data, commands, workflows, permissions, and UX — and let humans and AI agents operate against the same model with the same governance.

Zebric is a config-driven runtime that reads Blueprint files (TOML or JSON) and serves a working web app at runtime. Zebric interprets the Blueprint directly instead of generating application source code.

Blueprints themselves can be written by people or generated by AI tools. Zebric is designed to be LLM-friendly and extensible.

What Is Zebric?

Zebric is a runtime engine for building web apps from Blueprint configuration files. Instead of scaffolding an app and then maintaining generated code, you describe your data model, commands, pages, forms, and workflows declaratively, and Zebric interprets that Blueprint at runtime.

It is best suited to internal tools, admin surfaces, CRUD workflows, prototypes, and AI-assisted application development. When you need to go beyond the built-ins, you can extend Zebric with custom behaviors, layouts, plugins, and workflows.

Key characteristics:

• Configuration-driven: Define entities, routes, and forms in TOML/JSON instead of code
• Runtime interpretation: No build step; changes to Blueprint files are reflected immediately
• Server-side rendering: Traditional HTML pages with form submissions (not a SPA framework)
• Database integration: Automatic schema generation and CRUD operations from entity definitions
• AI-friendly: Designed for AI code generators to create and modify applications iteratively

Start Here

• Documentation: docs.zebric.dev
• Playground and examples: playground.zebric.dev
• npm package: @zebric/cli

Project Structure

zebric/
├── packages/
│   ├── runtime-core/       # Platform-agnostic engine and ports
│   ├── runtime-node/       # Node.js adapter (SQLite/PostgreSQL, Redis, filesystem)
│   ├── runtime-worker/     # Cloudflare Workers adapter (D1, KV, R2)
│   ├── runtime-hono/       # Hono HTTP adapter shared by runtimes
│   ├── runtime-simulator/  # In-memory runtime used by tests and the simulator
│   ├── cli/                # `zebric` command-line tool
│   ├── plugin-sdk/         # Plugin development SDK
│   ├── themes/             # Built-in themes
│   ├── notifications/      # Notification adapters (email, Slack, console)
│   ├── observability/      # Structured logging
│   ├── framework-stories/  # Blueprint-based integration stories
│   ├── react-simulator/    # React-based blueprint simulator
│   ├── playground/         # Interactive browser playground
│   └── docs/               # Public documentation site (Starlight)
├── plugins/                # Built-in plugins
├── examples/               # Example applications (blog, zebric-dispatch, …)
├── starters/               # Starter templates
├── docs/                   # Architecture and project documentation
├── scripts/                # Repository automation and maintenance scripts
├── benchmark/              # Benchmark harnesses and reports
└── monitoring/             # Local monitoring configuration

Quick Start

Using npm

# Install Zebric CLI globally
npm install -g @zebric/cli

# Or use with npx (no installation needed)
npx @zebric/cli --version

# Create a new directory for your project
mkdir my-app
cd my-app

# Create a blueprint.toml file with the contents below

version = "0.6.0"

[project]
name = "My Blog"
version = "1.0.0"
description = "A simple blog"

[project.runtime]
min_version = "0.6.0"

[entity.Post]
fields = [
  { name = "id", type = "ULID", primary_key = true },
  { name = "title", type = "Text", required = true },
  { name = "body", type = "LongText", required = true },
  { name = "published", type = "Boolean", default = false },
  { name = "createdAt", type = "DateTime", default = "now" }
]

[page."/"]
title = "All Posts"
auth = "none"
layout = "list"

[page."/".query.posts]
entity = "Post"
orderBy = { createdAt = "desc" }

[page."/posts/new"]
title = "New Post"
auth = "none"
layout = "form"

[page."/posts/new".form]
entity = "Post"
method = "create"

[[page."/posts/new".form.fields]]
name = "title"
type = "text"
label = "Title"
required = true

[[page."/posts/new".form.fields]]
name = "body"
type = "textarea"
label = "Body"
rows = 10
required = true

[page."/posts/new".form.onSuccess]
redirect = "/"
message = "Post created!"

[page."/posts/:id"]
title = "Post Detail"
auth = "none"
layout = "detail"

[page."/posts/:id".query.post]
entity = "Post"
where = { id = "$params.id" }

Then start the development server:

zebric dev --blueprint blueprint.toml --seed
# Or without a global installation:
# npx @zebric/cli dev --blueprint blueprint.toml --seed

# Visit http://localhost:3000

Development from source

# Clone the repository
git clone https://github.com/ZapCircleHQ/zebric.git
cd zebric

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run an example app
cd examples/blog
npx zebric dev --blueprint blueprint.toml

# Visit http://localhost:3000

For more patterns, continue with the documentation and examples.

Technology Stack

• Runtime: Node.js 22+
• Language: TypeScript
• HTTP Server: Hono 4.x
• Database ORM: Drizzle ORM with SQLite and PostgreSQL
• Authentication: Better Auth (Other providers in the future)
• Background Jobs: BullMQ (optional)
• Caching: Redis (optional)
• Styling: Tailwind CSS

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run all unit and integration tests across every package
pnpm test

# Run tests for a single package
pnpm --filter @zebric/runtime-core test
pnpm --filter @zebric/runtime-node test

# Watch mode for development
pnpm --filter @zebric/runtime-node test:watch

# Run the Playwright browser suite (see TESTING.md for tag-specific commands)
pnpm --filter @zebric/runtime-node test:browser

For detailed testing information, see TESTING.md.

Current Capabilities

HTTP & Routing

• Dynamic route matching (/posts/:id)
• HTTP methods: GET, POST, PUT, DELETE
• Form submission and validation
• Query parameter handling

Database

• Schema generation from Blueprint entity definitions
• CRUD operations via Drizzle ORM
• SQLite and PostgreSQL support
• Auto-generated REST API endpoints
• Access control rules at the entity and field level

Authentication & Security

• Email/password authentication via Better Auth
• Session management
• Role-based access control
• CSRF protection
• Security headers (CSP, XSS protection, etc.)

HTML Rendering

• Server-side HTML generation
• Layout types: list, detail, form, dashboard
• Tailwind CSS for styling
• View Transitions API support

Developer Tools

• Hot reload when Blueprint files change
• Admin endpoints for debugging
• Request tracing and metrics
• Audit logging

Current Limitations

Zebric is still evolving. A few practical limitations to keep in mind:

• Production readiness: Suitable for exploration and early projects, but not yet broadly battle-tested for production use
• Database support: SQLite and PostgreSQL are supported today
• Client-side interactivity: Limited JavaScript; primarily server-rendered HTML with form submissions
• Performance: The runtime approach trades some raw performance for iteration speed, and performance work is ongoing
• Ecosystem: The plugin ecosystem is still early
• Breaking changes: Blueprint schema details and APIs may still change as the project matures

MCP Server (Agent API)

Technical preview. The discovery contract and stdio MCP adapter are implemented and tested; see Agent API.

@zebric/mcp-server exposes a running Zebric application's Agent API to any MCP client (Claude Code, Claude Desktop, etc.) over stdio. Read operations are available automatically; each mutation must be opted in by its exact OpenAPI operation ID with a repeatable --allow-mutation flag. Zebric's existing HTTP authorization, validation, idempotency, workflow, and audit paths stay authoritative. The adapter also supports Claude Code's experimental Channels capability, forwarding authenticated, redacted entity and workflow events from the application's Agent API event stream.

Start your Zebric app first, then point the adapter at it with --connect.

Claude Code

# Read-only tools
claude mcp add zebric -- npx -y @zebric/mcp-server \
  --connect http://127.0.0.1:3000

# With bearer auth and a specific mutation allowed
claude mcp add zebric \
  --env ZEBRIC_API_KEY=your-secret \
  -- npx -y @zebric/mcp-server \
  --connect http://127.0.0.1:3000 \
  --credential-env ZEBRIC_API_KEY \
  --allow-mutation task_tracker_create_task

The credential is read from the environment (--credential-env) so it never appears on the command line or in shell history.

Claude Desktop

Add an entry to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "zebric": {
      "command": "npx",
      "args": [
        "-y", "@zebric/mcp-server",
        "--connect", "http://127.0.0.1:3000",
        "--credential-env", "ZEBRIC_API_KEY",
        "--allow-mutation", "task_tracker_create_task"
      ],
      "env": { "ZEBRIC_API_KEY": "your-secret" }
    }
  }
}

Restart Claude Desktop to load the server.

See examples/task-tracker for a working end-to-end setup.

Use Cases

Zebric works well for:

• Rapid prototyping and MVPs
• Internal tools and admin panels
• AI-assisted application generation
• Learning full-stack web development concepts
• CRUD applications with standard patterns

Zebric may not be suitable for:

• Applications requiring complex client-side interactivity
• High-traffic production systems (until more testing is done)
• Projects requiring integrations that are not yet covered by existing plugins or custom behaviors
• Applications with strict performance requirements

Documentation

• Domain commands and protected lifecycle state

• Full documentation: docs.zebric.dev

• Interactive examples and playground: playground.zebric.dev

• Repository testing guide: TESTING.md

• Release history: CHANGELOG.md

License

MIT License - Copyright (c) 2026 Biscotti Labs LLC