Setup

Add Corsair Hub to a TypeScript app in five steps. Your app registers itself with Hub the first time it serves a request, so there is no delivery URL to type into the dashboard. The App sync indicator in the header turns green when it connects.

Prefer to hand this to a coding agent? Point it at this page: “Set up Corsair Hub in this app. Follow https://docs.corsair.dev/hub/setup.md end to end.” It works through the same five steps below.

Prerequisites

A Hub project. Open your project’s Keys tab in the dashboard to copy its API key and signing secret. Secrets are shown once, so never log or commit them.

1. Install Corsair and a plugin

npm i corsair @corsair-dev/github

@corsair-dev/github is an example. Swap it for the integration your app needs. Browse the integrations catalog for plugin ids: each page’s slug is the id.

2. Create `corsair.ts` and link your database

corsair.ts

import "dotenv/config";

import { createCorsair } from "corsair";
import { github } from "@corsair-dev/github";

export const corsair = createCorsair({
    kek: process.env.CORSAIR_KEK!,
    database: db,
    hub: {
        projectApiKey: process.env.CORSAIR_API_KEY!,
        signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
    },
    plugins: [github()],
});

Pass your app’s database as database. Corsair persists connections and synced data there. Hub keeps no copy of your users’ tokens; it holds only the OAuth client id and secret (see Where your credentials live).

3. Add the `/api/corsair` route

The handler serves Hub delivery, meaning OAuth callbacks, connect pages, and self-registration, plus the management API, at its base path. Mount the adapter for your server:

Next.js
Express
Hono
Web-standard

app/api/corsair/[[...path]]/route.ts

import { toNextJsHandler } from 'corsair';
import { corsair } from '@/server/corsair';

export const { GET, POST, OPTIONS } = toNextJsHandler(corsair, {
    basePath: '/api/corsair',
});

Pages Router? Export a catch-all API route at pages/api/corsair/[...path].ts and forward req/res through the same toNextJsHandler. The App Router is the supported default.

server.ts

import express from 'express';
import { toExpressHandler } from 'corsair';
import { corsair } from './corsair';

const app = express();

// Required: Hub delivers results as JSON POSTs. The adapter reads the parsed
// body, so express.json() must run before the Corsair route.
app.use(express.json());
app.use('/api/corsair', toExpressHandler(corsair, { basePath: '/api/corsair' }));

app.listen(3000);

Mount express.json() before the Corsair route. Without it, req.body is undefined and Hub’s delivery POSTs arrive empty, so connects will look like they hang.

index.ts

import { Hono } from 'hono';
import { toHonoHandler } from 'corsair';
import { corsair } from './corsair';

const app = new Hono();

// Wildcard: Corsair routes several paths under the base (delivery, connect,
// tenants). Match them all with `/*`, and keep basePath in sync with the mount.
app.all('/api/corsair/*', toHonoHandler(corsair, { basePath: '/api/corsair' }));

export default app;

Every adapter wraps one primitive. managementHandler(corsair) returns (request: Request) => Promise<Response>. Any framework whose routes speak the Fetch API calls it directly, no adapter needed.

// src/routes/api/corsair/[...path]/+server.ts
import { managementHandler } from 'corsair';
import { corsair } from '$lib/server/corsair';

const handler = managementHandler(corsair, { basePath: '/api/corsair' });
export const GET = ({ request }) => handler(request);
export const POST = ({ request }) => handler(request);

// app/routes/api.corsair.$.ts
import { managementHandler } from 'corsair';
import { corsair } from '~/server/corsair';

const handler = managementHandler(corsair, { basePath: '/api/corsair' });
export const loader = ({ request }) => handler(request);
export const action = ({ request }) => handler(request);

// src/pages/api/corsair/[...path].ts
import { managementHandler } from 'corsair';
import { corsair } from '../../../server/corsair';

const handler = managementHandler(corsair, { basePath: '/api/corsair' });
export const GET = ({ request }) => handler(request);
export const POST = ({ request }) => handler(request);
export const prerender = false;

// server/routes/api/corsair/[...path].ts
import { fromWebHandler } from 'h3';
import { managementHandler } from 'corsair';
import { corsair } from '~/server/corsair';

// h3's fromWebHandler adapts the (Request) => Response handler to Nitro.
export default fromWebHandler(
    managementHandler(corsair, { basePath: '/api/corsair' }),
);

import { managementHandler } from 'corsair';
import { corsair } from './corsair';

const handler = managementHandler(corsair, { basePath: '/api/corsair' });
export default { fetch: (request: Request) => handler(request) };

Backend not in JavaScript? Corsair’s SDK is TypeScript-only. Integrate over the Hub REST API instead.

You do not put the delivery URL in your hub config; it is resolved per environment (see Delivery URLs).

4. Add your keys to `.env`

Copy the values from your project’s Keys tab. Never commit them.

.env

CORSAIR_API_KEY=ck_dev_...
CORSAIR_SIGNING_SECRET=...
CORSAIR_KEK=...

The env var names are your choice. The dashboard uses CORSAIR_API_KEY and CORSAIR_SIGNING_SECRET for both environments — the key value itself (ck_dev_… / ck_prod_…) tells the SDK which one you’re in. Match whatever you reference in corsair.ts.

5. Start your app

npm run dev

The first request to /api/corsair registers this app’s delivery URL with Hub automatically. The App sync indicator in the dashboard header turns green once you are connected.

Only development keys self-register. When your local app opens a Corsair tunnel, Hub delivers over it; otherwise it derives a local delivery target (overridable with CORSAIR_DELIVERY_URL) and falls back to a browser redirect. See Delivery URLs for details and production setup.

What’s next

Delivery URLs

How development and production delivery differ.

Environments

Development vs production keys.

Connect / OAuth

Mint a connect link so users can sign in.

Dashboard

Manage keys, connections, and delivery URLs.

Get Started

Frameworks

Adapters

Workflows (beta)

Reference

Prerequisites

1. Install Corsair and a plugin

2. Create `corsair.ts` and link your database

3. Add the `/api/corsair` route

4. Add your keys to `.env`

5. Start your app

What’s next

Delivery URLs

Environments

Connect / OAuth

Dashboard

​Prerequisites

​1. Install Corsair and a plugin

​2. Create corsair.ts and link your database

​3. Add the /api/corsair route

​4. Add your keys to .env

​5. Start your app

​What’s next

Delivery URLs

Environments

Connect / OAuth

Dashboard

Prerequisites

1. Install Corsair and a plugin

2. Create `corsair.ts` and link your database

3. Add the `/api/corsair` route

4. Add your keys to `.env`

5. Start your app

What’s next