Install MainSDK

MainSDK is a library, a CLI and an MCP server that live in your repo. There is nothing to host and no sidecar to run: you import it like any other package.

Nothing is published yet: MainSDK is pre-release, and these steps are the planned design. What runs from the repository today, and how to run it, is in the README. The Next.js, Hono, Express, worker, Prisma and Drizzle adapters are planned for milestone 0.2.

Starting from an empty folder? Skip to the quickstart; it creates a Next.js app and runs init for you. Read on to add MainSDK to a project you already have, or to wire in a framework other than Next.js.

Requirements

MainSDK is pure TypeScript with zero runtime dependencies: no native binary, no WebAssembly core and no install scripts.

Install

Run init in the root of your project. It installs the packages, writes a minimal main.yaml, adds .mainsdk/ to .gitignore and connects your coding agent. It needs no account and no network.

npx mainsdk init

pnpm dlx mainsdk init

bunx mainsdk init

To add the packages by hand instead:

npm install mainsdk
npm install --save-dev @mainsdk/cli @mainsdk/testing

pnpm add mainsdk
pnpm add -D @mainsdk/cli @mainsdk/testing

bun add mainsdk
bun add -d @mainsdk/cli @mainsdk/testing

The packages are ES modules only (ADR-0045) and ship built files with source maps. import them, or require() them on Node.js 22.12 or later.

Wire in your framework

One import puts every request and job behind MainSDK: each gets a trace, its user and market context, the lifecycle hooks, and errors returned as problem details.

// proxy.ts (middleware.ts on Next.js 15)
import { mainsdk } from "mainsdk/next";
export const proxy = mainsdk.proxy();

// app/api/orders/route.ts
import { withMainSDK } from "mainsdk/next";
import { auth, db } from "mainsdk";

export const GET = withMainSDK(async (req) => {
  const session = await auth.require(req);
  return Response.json(await db.orders.for(session.user).list({ limit: 20 }));
});

import { Hono } from "hono";
import { mainsdk } from "mainsdk/hono";

const app = new Hono();
app.use("*", mainsdk());
export default app;

import express from "express";
import { mainsdk } from "mainsdk/express";

const app = express();
app.use(mainsdk());
// … your routes
app.use(mainsdk.errors());   // last: turns errors into problem details
app.listen(3000);

import { worker } from "mainsdk/worker";
import { log } from "mainsdk";

export default worker(async (job, ctx) => {
  log.info("job started", { job: job.name });   // carries the producer's trace and user
});

Next.js support covers the App Router (route handlers, server actions and proxy.ts or middleware.ts). The Pages Router is not supported.

Prisma and Drizzle

Wrap your existing client so every query goes through the policy engine and the audit log. mainsdk check reports any query made with the unwrapped client (MAIN-DATA-0001).

import { PrismaClient } from "@prisma/client";
import { withPrisma } from "mainsdk/prisma";

export const prisma = withPrisma(new PrismaClient());

import { drizzle } from "drizzle-orm/node-postgres";
import { withDrizzle } from "mainsdk/drizzle";
import { pool } from "./pool";

export const db = withDrizzle(drizzle(pool));

Check the install

npx mainsdk info

info reads main.yaml and prints the app, its interfaces and drivers, network destinations, data labels and regions, and open exceptions. Add --json for a versioned document. If it prints your app, you're set.

What runs when

Nothing is published yet. Milestone 0.2: init, check, sync, info, logs, dev and local config, secrets, policy and log. Milestone 0.3: init --preset, add, doctor, check --json --agent and local auth, db and ai. Milestone 0.4: the testing kit. Milestone 0.5: public beta, the migration skill and adopt.

Next

• Quickstart: build a checked app from an empty folder
• Interfaces and drivers
• CLI reference