@superinterface/server overview

The Superinterface server is a pre-built Next.js runtime that exposes the same REST endpoints we use in production. It ships with migrations, background task scheduling, and a CLI for managing organizations and API keys. You can run the packaged server directly from npm, or fork the source to customize behavior.

What you get out of the box

A fully typed REST API for assistants, messages, runs, files, workspaces, tasks, and providers.

Prisma schemas and migrations backed by Postgres, with adapters for Neon/Vercel Postgres and direct connections such as Supabase.

A task scheduler that uses Upstash QStash to trigger recurring work.

A CLI (@superinterface/server) for seeding organizations, creating API keys, and starting the runtime.

TypeScript definitions so your own Next.js apps can import the same handlers.

Deployment building blocks

Component	Purpose	Notes
Next.js runtime	Serves every REST endpoint under `/api` and static assets.	Runs in production mode; build output is bundled inside the published npm package.
Prisma ORM	Owns migrations and generates the database client.	Uses the Neon adapter by default, but can fall back to a standard Postgres client for Supabase and other providers. Migrations run through `prisma migrate`.
PostgreSQL	Stores every organization, assistant, thread, file, and task.	Neon (Vercel Postgres) and Supabase are tested. Any serverless Postgres that Prisma supports will work when you select the right adapter.
Upstash QStash	Delivers scheduled task callbacks.	Optional, but required if you rely on cron-like tasks.
Upstash Workflow (optional)	Powers long-running task orchestration.	Shares the same `QSTASH_TOKEN`.

Baseline requirements

Node.js 20+ (the CLI and runtime target ESM modules and Next.js 15).

Postgres 15+ reachable via a pooled connection string. Neon/Vercel Postgres is the default, but Supabase (with the pooled connection string) and any other Prisma-supported Postgres host works by switching the adapter.

Environment variables listed below must be available either through a .env file or the process environment.

(Optional) Upstash QStash token if you plan to schedule tasks or use Upstash Workflow helpers.

If no .env file exists, the CLI simply reads from process.env. This makes it safe to inject secrets via your hosting provider instead of shipping them in the image.

Environment variables

Variable	Required	Description
`DATABASE_URL`	Yes	Connection string used by the runtime. For Neon/Vercel Postgres use the pooled URL; for Supabase use the pooled (pgBouncer) URL.
`DIRECT_URL`	Yes (Neon)	Direct Postgres connection string used by `prisma migrate`. Neon/Vercel Postgres provides this; for Supabase you can reuse `DATABASE_URL`.
`DATABASE_ADAPTER`	Optional	Controls which Prisma adapter the server loads. Supported values: `neon` (default) or `direct` (use this for Supabase and any standard Postgres provider).
`NEXT_PUBLIC_SUPERINTERFACE_BASE_URL`	Yes	Absolute base URL of the server (for example, `https://api.example.com`). Used for scheduled callbacks and public asset URLs.
`QSTASH_TOKEN`	Optional	Upstash QStash token. Required for scheduled tasks and Upstash Workflow integration.
`QSTASH_CURRENT_SIGNING_KEY`	Optional	Enables signature verification for incoming QStash webhooks. Leave unset for local development.
`COMMUNITY_TEST_GROQ_API_KEY`	Optional	Fallback API key for Groq models when one is not stored on a provider record.

After the server is running you will still need to seed at least one organization and organization API key. The CLI ships commands for both and they work against any environment as long as the correct database credentials are set.