Skip to Content

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/orders

From this tree, manh.run builds three parts:

  • UI: page.tsx and layout.tsx files become a React app built with antd and pro-components.
  • API: each get.ts, post.ts, put.ts, patch.ts or delete.ts file is a Hono endpoint with Zod-validated input.
  • Database: each *.table.ts file 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.

  • .tsx runs in the browser: pages, layouts, components. It can’t import app/db, *.table.ts, hono, drizzle-orm or manh/env.
  • .ts runs on the server: handlers, middleware, cron jobs, tables, repositories. It can’t import react or use window, document or localStorage.

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.

app/orders/get.ts
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 JSON

From code to a running app

Your agent writes files; manh.run does the rest. Each step is an MCP tool.

  • write_files never deploys. The workspace preview changes at once; the running app doesn’t.
  • check runs the cheapest layers first. Each error comes with the file, the line and how to fix it.
  • deploy refuses while check reports 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.run shows 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.ts and app/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

Last updated