Quickstart
Set an app up with one command, define a table, push it, and query it with types.
You need Node.js 22.18 or newer and a Mantis account. Run everything from your app's folder.
Set the app up
npx shipmantis@latest initinit prints a short code and opens the browser:
Your code: WDJB-MJHT
Approve it in the browser: https://app.shipmantis.com/terminal?code=WDJB-MJHTApprove the code there while signed in to Mantis, and the terminal carries on. It asks which project to use, or what to call a new one (the folder's name by default), writes the files below, and ends with the next steps and a link to the project in the dashboard.
Pass --new <name> to create a project without the menu, or --project <slug> to use an
existing one. On an existing project, init makes a new key pair named after this machine;
keys on other machines keep working, and each can be revoked on its own.
Install the SDK
npm install @shipmantis/sdkDefine a table
import { defineSchema, t, table } from "@shipmantis/sdk";
export default defineSchema({
todos: table({
title: t.text(),
done: t.boolean().default(false),
}),
});Query it
import { createClient } from "@shipmantis/sdk";
import schema from "../mantis/schema";
export const mantis = createClient({
url: process.env.MANTIS_URL!,
key: process.env.MANTIS_SECRET_KEY!,
schema,
});const todos = mantis.from("todos");
await todos.insert({ title: "Ship it" });
const open = await todos.select({ where: { done: false } });
// ^? { id: string; createdAt: string; title: string; done: boolean }[]What init wrote
| File | What it holds |
|---|---|
.env.local | MANTIS_URL, MANTIS_SECRET_KEY and MANTIS_PUBLISHABLE_KEY. Added to .gitignore. |
.mcp.json | The mantis MCP server for Claude Code: npx -y shipmantis mcp. |
.codex/config.toml | The same server for Codex, as [mcp_servers.mantis]. |
.claude/skills/mantis/SKILL.md | How the agent should change the backend: plan first, branch for risky changes, wait for held changes. |
AGENTS.md | The same instructions between <!-- mantis:start --> and <!-- mantis:end -->, for Codex and other agents. |
Running init again updates its own lines and sections in these files and leaves the rest of
each file alone. SKILL.md is the exception: it belongs to Mantis and is rewritten whole.
Never commit .env.local or paste the secret key anywhere public. It can read and change every
row. If it leaks, reset it from the project's page in the dashboard.
Next
From here, ask your agent for features. It reads the schema with the MCP tools, edits
mantis/schema.ts, plans the migration and applies it. Anything on main that could lose data
waits for you in the dashboard.