Run locally with Node.js

Use this guide when you want to run the production server on your laptop or a self-managed VM. You only need Node.js and access to a serverless Postgres database (Neon, Vercel Postgres, Supabase, or any provider Prisma supports).

Prerequisites

Node.js 20 or newer and npm (or pnpm/bun) installed locally.

A Postgres database. Neon/Vercel Postgres or Supabase provide the pooled URLs the server expects.

(Optional) An Upstash QStash project if you plan to schedule recurring tasks.

1. Create a working directory and `.env`

Pick an empty folder, then add a .env file. The CLI looks for it automatically.

mkdir superinterface-server && cd superinterface-server cat <<'EOF' > .env DATABASE_URL=postgres://... DIRECT_URL=postgres://... NEXT_PUBLIC_SUPERINTERFACE_BASE_URL=http://localhost:3000 # DATABASE_ADAPTER=direct # Optional: use for Supabase or self-managed Postgres # Optional extras: # QSTASH_TOKEN= # QSTASH_CURRENT_SIGNING_KEY= # COMMUNITY_TEST_GROQ_API_KEY= EOF

Tip: For local development you can point DATABASE_URL and DIRECT_URL to the same value. Set DATABASE_ADAPTER=direct when you are not using Neon/Vercel Postgres.

2. Run database migrations

The server publishes a CLI under @superinterface/server. Use it with npx (or install it globally) to apply the migrations.

npx @superinterface/server@latest prisma deploy

The command runs prisma migrate deploy against the connection strings in your environment and generates the Prisma client if it does not exist yet.

3. Seed an organization and API key

Every request from the client authenticates with an organization-scoped API key. Create one with the bundled prompts:

npx @superinterface/server@latest organizations create npx @superinterface/server@latest organizations api-keys create

Both commands are interactive and will reuse the same environment variables you set earlier.

4. Start the production server

Launch the runtime on any free port. When the CLI starts it verifies the .next build embedded in the npm package and boots Next.js in production mode.

npx @superinterface/server@latest run server --port 3000

Visit http://localhost:3000/api/workspaces with your freshly created API key to confirm the server is responding:

curl http://localhost:3000/api/workspaces \ -H "Authorization: Bearer <organization-api-key>"

You should receive a JSON response (an empty list on a fresh database).

5. Connect your products

Call the REST endpoints under /api/** directly from your application code. Authenticated endpoints expect the organization API key in the Authorization: Bearer header.

For Next.js apps, you can import the prebuilt route handlers from @superinterface/server/next/api/... if you prefer to co-locate the API within your own project.

When you are ready to deploy, you can reuse the same .env file and API key with any hosting provider.