Run Kurabase locally

The local command builds from this checkout and starts Anvil, deploys a fresh instance, creates an instance-held operator, grants the ordinary and administrative gateways, then starts the Dashboard.

Prerequisites

• Node.js 20 or later.
• pnpm 10.
• Docker Desktop.

Start the stack

From the repository root:

pnpm install
pnpm kura start

The default local endpoints are:

Service	Address
Application gateway	http://127.0.0.1:55421
Administrative gateway	http://127.0.0.1:55422
Dashboard	http://127.0.0.1:55423
Anvil RPC	http://127.0.0.1:8545

Use pnpm kura status as the source of truth for public endpoints and the publishable key. Bootstrap creates and retains the local operator credential and a separate dev-server key. Neither is printed by status or belongs in a browser.

caution

The publishable key identifies the project. It is safe to use in a browser. Gateway signing material, server credentials, and wallet session tokens are never setup values that you paste into the Dashboard.

Configure Privy in Dashboard

Open the local Dashboard and select Authentication under Project. Enter the public Privy App ID and, when relevant, a public ZeroDev project ID, then save. kura start persists only these browser-safe identifiers in the local instance state; the application gateway discovers the change immediately, with no restart and no pasted server key.

Adding a Privy App ID changes ordinary application mutations into gateway-attested, account-owned transaction plans. Pass those plans to your application's Privy/ZeroDev sender. Removing the App ID returns the disposable Anvil instance to its direct-commit development path. Dashboard SQL and migrations remain local-operator actions and are not affected.

This Dashboard setting is public transaction-delivery configuration, not a local Privy-token verifier or a browser login integration. A frontend still creates its user bearer through db.auth.signInWithWallet({ provider }), or through the separately configured custom/hosted Privy issuer described in the JavaScript SDK guide. After saving a Privy App ID, provide the SDK's transaction.send callback for application mutations; the local stack does not create a Privy or ZeroDev sender for your app.

The Dashboard has no secret field: all saved values are treated as public and browser-discoverable. Keep Privy secrets, ZeroDev paymaster/bundler credentials and session keys in the provider-side service; they do not belong in a local project setting or browser bundle.

Call the application gateway from your frontend

Browser applications may call the application gateway directly. Use the public application URL and publishable key reported by pnpm kura status; no developer-managed CORS proxy is required for normal SDK or REST use. For example, an app served on http://localhost:3010 can call the default local gateway at http://127.0.0.1:55421 with @kurabase/js.

The gateway answers CORS preflights for SDK headers and opts in to local Private Network Access. Keep the administrative gateway and KURA_DEV_SERVER_KEY on a trusted server or inside the local Studio proxy. They are not frontend setup values.

If the default ports conflict, set all three gateway and Dashboard ports together before starting:

KURA_APP_PORT=56421 \
KURA_ADMIN_PORT=56422 \
KURA_STUDIO_PORT=56423 \
pnpm kura start

Use pnpm kura logs [service] to inspect a service. Use pnpm kura stop to stop a stack that has saved its local Anvil state. pnpm kura db reset --yes is the explicit destructive reset.

Recover a failed bootstrap

If kura start reports service "bootstrap" didn't complete successfully: exit 1, read the bootstrap error before changing state:

pnpm kura logs bootstrap

Bootstrap verifies that its saved instance metadata, delegated gateways, and the persisted Anvil chain describe the same instance. The common message Recorded Kurabase contract no longer exists means an old kura-state volume names a contract that is absent from the current Anvil state volume. This can happen if a local Docker volume was removed independently or an older local stack was recreated incompletely. Recorded Kurabase contract predates Dashboard wallet management means the saved local instance uses an older ABI and must be explicitly redeployed before browser management is available. These are safety checks: Kurabase will not silently connect gateways to a different chain or contract.

If all local data is disposable, recreate the complete local environment:

pnpm kura db reset --yes
pnpm kura start

Data loss

kura db reset --yes deletes the local Anvil chain, the instance state, both local gateway signer volumes, and all chain-backed local data. Back up data you need before using it. For any other bootstrap message, keep the volumes intact and use the exact output from kura logs bootstrap to diagnose the failure.

Apply a migration

Create a timestamped SQL file in your migration directory:

supabase/migrations/202609100001_create_posts.sql

create type post_state as enum ('draft', 'published', 'archived');

create table posts (
  id bigint primary key,
  author_id uuid not null,
  title text not null,
  state post_state not null default 'draft'
);

alter table posts enable row level security;

For a running local stack, the CLI discovers the administrative endpoint and gateway-held server credential through its Compose status. No URL or environment variable is needed:

pnpm kura migration up --dir supabase/migrations

The runner sorts valid timestamped files, reads applied versions from the gateway, skips them, and posts each remaining file as one atomic migration. A version is recorded only after success.

Query the database

The SQL query command uses the same discovered local administrative endpoint and generated dev-server credential without exposing either:

pnpm kura db query --query 'select id, title from posts'

For a file, use --file path.sql instead of --query. For a remote or non-local gateway, pass --url and set KURA_DEV_SERVER_KEY (or the legacy KURA_SECRET_KEY) in the trusted shell; each explicit value takes precedence over locally discovered status.

Give a trusted dev server service access

The local Dashboard manages the instance through its server-side local operator proxy. A browser never needs the service key. If a server route, worker, or local backend needs the same service authority, request the generated key explicitly:

pnpm kura key dev

Put the printed KURA_DEV_SERVER_KEY only in that server's .env.local and use the administrative gateway URL. The key is intentionally absent from kura status, public instance metadata, and the Dashboard JavaScript. It can bypass RLS through the privileged local gateway, so do not expose it to client code. See dev-server keys.

Open the Dashboard

Open http://127.0.0.1:55423. The Dashboard asks its same-origin Studio proxy for the local, non-sensitive instance address and opens that workspace automatically. The proxy authenticates to the delegated local operator; no secret key, pasted token, or browser wallet is needed for local SQL and migrations.

The Table Editor is the default database workspace. Use New table to define a table and its columns without writing SQL, select a table to browse its rows, and use Insert row, a row's edit action, or Delete to manage records. The SQL Editor remains available for migrations, queries, and operations that are better expressed as SQL. All of these local management actions go through the same chain-backed administrative gateway; the visual editor is not a separate mock database.

For remote instances, the Dashboard retains the EIP-712 owner/developer management session flow as a compatibility fallback. Wallet authority is also optional for user-owned RLS sessions. The local operator is a management identity only: it does not turn into a user session or allow the gateway to mint one.

Know the built-in auth catalog boundary

After a verified wallet or strict pseudonymous Privy session exchange, the gateway can register that user in the two reserved chain-backed relations kura_auth_users and kura_auth_identities. They are SELECT-own-records only, not a replacement for an authentication provider or private profile store. See automatic auth catalog before relying on their identifier, RLS, and public-chain-data constraints.