How manh.run works
One app/ tree becomes a React UI, an API and the app’s own SQLite database; your agent writes the code, and manh.run checks, previews and deploys it.
Manh is a full-stack framework for internal tools and admin apps. manh.run is the service that runs it: it stores your code, checks it, shows a live preview and runs the app for real users. manh.run runs no AI model of its own. Your agent (Claude Code, Claude, ChatGPT, Gemini and others) writes the code over MCP.
One tree, three parts of the app
The directory tree is the configuration: there is no route table, and adding a feature means adding a file. A few optional files at the root (app/auth.ts for sign-in, app/theme.tsx for colours and type) only switch features on.
app/
├── layout.tsx → shared frame for every page
├── page.tsx → page /
└── orders/
├── page.tsx → page /orders
├── orders.table.ts → the orders table in the database
├── repository.ts → business rules for orders
├── get.ts → GET /api/orders
└── post.ts → POST /api/ordersFrom this tree, manh.run builds three parts:
- UI:
page.tsxandlayout.tsxfiles become a React app built with antd and pro-components. - API: each
get.ts,post.ts,put.ts,patch.tsordelete.tsfile is a Hono endpoint with Zod-validated input. - Database: each
*.table.tsfile is a Drizzle table in the app’s own SQLite database.
The UI calls the API through useApiClient() from app/api. manh.run generates that file from your handlers, so function names and types always match the API.
The file extension decides where code runs
Both kinds of file sit side by side in app/, but they run in different places.
.tsxruns in the browser: pages, layouts, components. It can’t importapp/db,*.table.ts,hono,drizzle-ormormanh/env..tsruns on the server: handlers, middleware, cron jobs, tables, repositories. It can’t importreactor usewindow,documentorlocalStorage.
At build time, manh.run splits the two kinds into separate bundles. The UI and the server never import from each other. The one exception is app/shared/*.ts: types, constants, status lists (defineEnum) and pure functions that both sides need, written once.
import { z } from "@hono/zod-openapi";
import { listOrders } from "./repository"; // only .ts files can import the repository
export const schema = { query: z.object({ status: z.string().optional() }) };
export default (c, { query }) => listOrders(query); // return an object → manh.run sends JSONFrom code to a running app
Your agent writes files; manh.run does the rest. Each step is an MCP tool.
write_filesnever deploys. The workspace preview changes at once; the running app doesn’t.checkruns the cheapest layers first. Each error comes with the file, the line and how to fix it.deployrefuses whilecheckreports errors. The UI and the API go live in one step, so users never see a new UI calling an old API. After each deploy, manh.run runs the app’s tests (spec/acceptance.json, or generated smoke tests until you write it) on a copy with its own database; live data is never touched.- Checkpoints you name are kept (up to 100), plus the 10 newest automatic copies saved before each file change. To roll back, restore a checkpoint and deploy.
Good to know
- The app’s API answers 503 until the first deploy. The preview still shows the UI.
- Before the first deploy,
<id>.manh.runshows the live preview; after it, the deployed version. - Don’t create an
app/api/folder. The tree is flat:app/<resource>/<method>.ts. - manh.run generates
app/db.ts,app/api.tsandapp/hooks.ts; don’t edit them.
Where a request goes
The order is fixed: the user is resolved first, then every middleware.ts runs from parent to child folder, then access is checked, and only then the handler. Because access comes before the schema, a caller with the wrong role gets 403, never a 400 that shows the data shape.
Next steps
- Why the stack is fixed — why it’s antd, Hono, Drizzle and SQLite only.
- The app/ tree — every file type and the URL it maps to.
- Your first app — build an app from scratch to deploy.