instancez

instancez

An LLM-friendly, single-binary, drop-in replacement to Supabase.

Defined in one YAML file — self-hosted in seconds.

Quick start · Docs · Feature parity

Why instancez?

• One YAML file is the schema. Edit instancez.yaml and instancez diffs it against the live database, applying just the delta migration, with no migration files to write or run by hand. Drops need --allow-destructive under inz serve.
• Compatible with Supabase clients (@supabase/supabase-js, and others). Point your existing client at instancez and it works: auth, PostgREST-style REST, RPC, storage.
• Runs anywhere. One self-contained, portable binary — locally, in Docker, on a VM, or on AWS Lambda.
• LLM-friendly. A simple, easy-to-understand YAML schema — tables, RLS, storage, RPC, functions — one file an LLM (or teammate) can read end to end.

_{instancez.yaml and inz dev booting, then a live supabase-js app: anonymous sign-in, then insert / update / delete.}

_{The built-in dashboard at /dashboard. Under inz dev, schema edits write back to instancez.yaml as a diff you review before it applies.}

Quick start

# macOS / Linux
curl -fsSL https://get.instancez.ai | sh

# Windows (PowerShell):
irm https://get.instancez.ai/windows | iex

inz sends anonymous usage and error telemetry. Turn it off with inz telemetry disable or INSTANCEZ_TELEMETRY_DISABLED=1. See what is collected.

Or build from source. This needs Go 1.25+ and Node 22+. The dashboard is embedded into the binary, so build it before the Go install:

git clone https://github.com/instancez/instancez.git
cd instancez
(cd dashboard && npm ci && npm run build) && go install ./cmd/inz

mkdir my-app && cd my-app
inz init                # or start from a template: inz init --template blog (list: inz init --list-templates)
inz dev --embedded-pg   # no Postgres to install; or drop the flag and set INSTANCEZ_DATABASE_URL to use your own

# you can run the following command or watch the output of the previous command for your secret key and publishable key
cat .development.env    # in a separate terminal — publishable + secret keys, generated on first run

inz dev provisions the Postgres roles, applies the schema, and serves the API at http://localhost:8080. Editing instancez.yaml re-applies the schema automatically.

What's in the YAML?

Here's the whole app inz init scaffolds (instancez.yaml, comments trimmed):

version: 1

project:
  name: "my-app"

providers:
  storage:
    type: local

auth:
  jwt_expiry: 15m
  refresh_token_expiry: 7d
  email:
    verify_email: false

tables:
  profiles:
    rls_enabled: true
    fields:
      - name: id
        primary_key: true
        foreign_key:
          references: auth.users.id
          on_delete: cascade
      - name: name
        type: text
        required: true
      - name: avatar_path      # path of the file in the avatars bucket below
        type: text

    rls:
      # Profiles are readable by anyone signed in; users manage only their own.
      - operations: [select]
        using: "auth.is_authenticated()"
      - operations: [insert]
        with_check: "id = auth.uid()"
      - operations: [update]
        using: "id = auth.uid()"
        with_check: "id = auth.uid()"
      - operations: [delete]
        using: "id = auth.uid()"

  todos:
    rls_enabled: true
    fields:
      - name: id
        type: bigserial
        primary_key: true
      - name: user_id
        foreign_key:
          references: auth.users.id
          on_delete: cascade
      - name: title
        type: text
        required: true
      - name: status
        type: text
        required: true
        enum: [pending, active, done]
        default: pending
      - name: created_at
        type: timestamptz
        required: true
        default: now()
    rls:
      - operations: [select, insert, update, delete]
        using: "user_id = auth.uid()"
        with_check: "user_id = auth.uid()"

storage:
  avatars:
    public: true
    max_size: 5MB
    types: [image/*]
    rls:
      - operations: [select]
        using: "auth.is_authenticated()"
      - operations: [insert]
        with_check: "auth.is_authenticated()"
      - operations: [update]
        using: "auth.is_authenticated()"
        with_check: "auth.is_authenticated()"
      - operations: [delete]
        using: "auth.is_authenticated()"

functions:
  todos:
    runtime: node
    file: functions/todos.js
    auth_required: true

Query it with supabase-js:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('http://localhost:8080', process.env.INSTANCEZ_PUBLISHABLE_KEY)

const { data, error } = await supabase
  .from('todos')
  .select('*')

Or with curl:

curl 'http://localhost:8080/rest/v1/todos?select=*' \
  -H "apikey: $INSTANCEZ_PUBLISHABLE_KEY"

The scaffolded todos table has a user_id = auth.uid() RLS policy, so rows are scoped to the signed-in user. To read without signing in while you experiment, set using: "true" on the policy in instancez.yaml.

Coding agents

The repo ships an agent skill that teaches your coding agent the YAML syntax, RLS patterns, and the inz CLI. Install it into your project with the skills CLI, which supports Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Copilot, and more:

npx skills add instancez/instancez                  # auto-detects your agents
npx skills add instancez/instancez -a codex         # or target one explicitly

Claude Code users can install it as a plugin instead:

/plugin marketplace add instancez/instancez
/plugin install instancez@instancez

For any other agent, the skill is a single Markdown file: drop SKILL.md into your project and reference it from AGENTS.md. Details in the Coding Agents docs.

Hosting and Deployment

Self-host it yourself:

inz serve

Secrets load automatically from .production.env if present, alongside the regular process environment.

Or deploy to instancez Cloud:

inz cloud deploy   # push instancez.yaml straight to a managed project

Self-hosting also runs on Docker, Kubernetes, AWS Lambda, or a bare VM. More on deployment →

Feature parity

Examples

docs/examples/gearstore is a full, runnable project: a React storefront talking to instancez over @supabase/supabase-js, exercising auth, RLS, and querying end to end. docker compose up --build gets you a working app with seeded data.

The docs also walk through two smaller builds start to finish: an ecommerce store with Stripe Checkout, and a file gallery with direct-to-S3 uploads.

Documentation

Full docs live at instancez.github.io:

• Quick start
• Tables and schema
• Auth
• RLS policies
• Querying
• Supabase SDK compatibility
• Deploy

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for the dev setup, the test loop, and how the codebase is laid out. Bug reports and feature requests go through the issue templates.

Security

Found a vulnerability? Please follow the private disclosure process in SECURITY.md rather than opening a public issue.

License

Apache License 2.0, see LICENSE. Contributions are covered by the Contributor License Agreement.