Get started with instancez, a self-hosted Supabase alternative

instancez is an open-source backend that ships as one Go binary. You describe the whole backend in one file, instancez.yaml: tables, row-level security, auth, storage and functions. instancez turns that file into a Postgres schema and serves the same HTTP API as Supabase, so @supabase/supabase-js works against it unchanged.

You can self-host it on your own Postgres or run it on instancez Cloud. This post takes you from install to a project running on your machine, then shows both ways to put it online.

Install the inz CLI

On macOS or Linux:

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

On Windows, in PowerShell 5.1 or later:

irm https://get.instancez.ai/windows | iex

Check that it worked:

inz version

The installation guide has direct downloads if you’d rather not pipe a script into your shell. Run the install command again to update.

Create a project

mkdir my-app && cd my-app
inz init

inz init only writes files and never touches a database. You get an instancez.yaml, a .gitignore and example env files. If Node.js 22+ is on your PATH, it also scaffolds an example code function in functions/.

Read the instancez.yaml

Here’s the table the scaffold creates, trimmed:

tables:
  todos:
    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
    rls:
      - operations: [select, insert, update, delete]
        using: "user_id = auth.uid()"
        with_check: "user_id = auth.uid()"

The rls block is the one to understand. RLS is the only authorization layer in instancez. Each entry becomes a Postgres policy, and Postgres checks it on every request. This policy lets users read and write only their own rows. auth.uid() is NULL when nobody is signed in, so anonymous requests see nothing.

To make a table readable by everyone, add a separate policy:

      - operations: [select]
        using: "true"

Don’t set using: "true" on the existing policy. It also covers insert, update and delete, so everyone could write.

Run it locally

inz dev --embedded-pg

This starts a Postgres 16 that ships inside inz, with its data in ./pgdata/. The first run downloads it (about 30 MB). Add --reset-pg to start from an empty database. The flag only exists on inz dev; it’s for local development, not production.

On first boot, instancez applies your schema and generates two keys:

• a publishable key (inz_publishable_…) for browsers, mapped to the anon role
• a secret key (inz_secret_…) for servers only, mapped to service_role, which bypasses RLS

Both are printed at startup and saved to .development.env. The API listens on http://localhost:8080. There are no migration files to write: instancez diffs instancez.yaml against the database and applies only the change.

Query it with supabase-js

npm install @supabase/supabase-js

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

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

const { data: { user } } = await supabase.auth.signInAnonymously()

await supabase.from('todos').insert({ title: 'Try instancez', user_id: user.id })

const { data, error } = await supabase.from('todos').select('id, title, status')
console.log(data, error)

Run it with the keys from .development.env in your environment. You’ll see your row with status set to pending. Run the same select without signing in and you get an empty list, because of the RLS policy.

Email and password, magic links, OTP, Google and GitHub OAuth and TOTP MFA use the same supabase-js auth calls. The auth docs cover each one.

Open the dashboard

While inz dev runs, there’s a dashboard at http://localhost:8080/dashboard. Sign in with the secret key to browse tables, manage users, run SQL and copy keys. Schema edits you make there are written back to instancez.yaml as a diff you review first, so the file stays the source of truth.

Use your own Postgres

The embedded database is for trying things out. To self-host, and anywhere else, instancez runs against a Postgres 14+ that you provide: a local install, Neon, RDS and so on. Pass a superuser connection string instead of the flag:

export INSTANCEZ_DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
inz dev

For production, use inz serve. It reads INSTANCEZ_DATABASE_URL, INSTANCEZ_PUBLISHABLE_KEY and INSTANCEZ_SECRET_KEY from .production.env:

inz validate
inz serve --migrate

inz validate checks the config without connecting. --migrate applies pending schema changes on startup. serve has no hot reload, and the dashboard is off by default. The self-hosting comparison sums up what self-hosting gives you, and there are guides for Docker, AWS Lambda and a plain VM.

Deploy to instancez Cloud

If you don’t want to run Postgres and a server yourself, push the same file to instancez Cloud. Hosted plans include the database.

inz cloud login
inz cloud deploy --new

login signs you in through your browser. deploy --new validates your config, creates a cloud project and writes its id to project.cloud.project_id in instancez.yaml. Code functions are uploaded and built in the cloud.

After that, deploying a change is:

inz cloud deploy

It shows a diff and asks Deploy? [y/N] before changing anything. Pass --yes in CI. Each project has one live version, and a deploy updates it directly. inz cloud status shows the project’s URL and deploy status.

On the cloud, the Supabase-compatible API lives under /api on your app’s URL:

const supabase = createClient('<your app url>/api', '<publishable key>')

If you build with a coding agent, you can connect it to instancez Cloud over MCP instead. In Claude Code:

claude mcp add instancez --transport http https://my.instancez.ai/mcp

The agent can then create apps, edit their instancez.yaml, run SQL and read logs. Each config change it makes deploys right away.

The Free plan is $0 and Pro is $20/month; see pricing.

Where to go next

The docs have the full reference for schema, RLS, storage and functions. The source is on GitHub under Apache-2.0.