# manh.run

> manh.run is a hosted full-stack app builder for coding agents. Your agent (Claude Code, ChatGPT, Claude) connects over MCP at https://mcp.manh.run, writes an app on a locked stack (React + antd / pro-components UI, Hono + Drizzle API, its own SQLite database), and manh.run checks, previews and deploys it to <app>.manh.run with built-in email, AI, file storage, cron and rollback.

Connect from Claude Code: `claude mcp add --transport http manh https://mcp.manh.run`, then run /mcp to sign in. Full docs in one file: https://manh.run/llms-full.txt

## Get started

- [API handlers](https://docs.manh.run/en/getting-started/api-handlers.md): Each get.ts, post.ts, put.ts, patch.ts or delete.ts file is an endpoint. It exports a schema and a handler function, and manh.run sends the function's return value as JSON.
- [Sign-in and permissions](https://docs.manh.run/en/getting-started/auth.md): Turn on sign-in with one app/auth.ts file, declare who may call each API with access, sign in with Google and use the session in the UI.
- [AI and file storage](https://docs.manh.run/en/getting-started/built-ins.md): Call AI with manh/openai and store and share files with manh/blob from the app's server code, with no API key.
- [Check and fix errors](https://docs.manh.run/en/getting-started/check.md): check validates the project in four layers as soon as the agent writes files; errors block deploy, warnings don't, and every line names the file, the line and the fix.
- [ChatGPT](https://docs.manh.run/en/getting-started/connect/chatgpt.md): Add Manh to ChatGPT as a custom MCP server, sign in to manh.run, then call @Manh in a chat.
- [Claude Code and Claude](https://docs.manh.run/en/getting-started/connect/claude.md): Add Manh to Claude Code with one command, or to claude.ai and the Claude app from the connector directory.
- [Cursor and Codex](https://docs.manh.run/en/getting-started/connect/cursor-codex.md): Add Manh to Cursor with an mcp.json entry, or to the Codex CLI with one command, then sign in to manh.run in your browser.
- [Gemini](https://docs.manh.run/en/getting-started/connect/gemini.md): Add Manh to Gemini through Connected Apps, link your account, sign in to manh.run, then call @Manh in a chat.
- [Connect your agent](https://docs.manh.run/en/getting-started/connect.md): Add Manh to the agent you already use over MCP so it can create projects, write code, check it and deploy it with your account.
- [Scheduled jobs](https://docs.manh.run/en/getting-started/cron.md): Run work on a schedule (cancel stale orders every hour, send a report every morning) with a *.cron.ts file that is safe to re-run.
- [Call the API from the UI](https://docs.manh.run/en/getting-started/data-fetching.md): Call your app's own API from a React page with the generated useApiClient() client and the useRequest hook, including reloads, writes and error handling.
- [Database](https://docs.manh.run/en/getting-started/database.md): Each app has its own SQLite database; tables are declared in .table.ts files, queried with Drizzle in repository.ts, and the schema updates on deploy.
- [Deploy](https://docs.manh.run/en/getting-started/deploy.md): One deploy runs check, builds the UI and puts the UI and API live on the app's address together; with errors left, manh.run refuses and the running app stays as it was.
- [Send and receive email](https://docs.manh.run/en/getting-started/email.md): An app sends email with manh/email and receives mail sent to its own address with a *.email.ts file, with no mail server or API key.
- [Your first app](https://docs.manh.run/en/getting-started/first-app.md): Give your agent a short brief, review the spec it writes, watch the app run in the dashboard preview and ask for changes. The example is a purchase-approval app.
- [Introduction](https://docs.manh.run/en/getting-started/introduction.md): Your AI agent builds business apps on manh.run. manh.run checks them, previews them, deploys them and gives every app its own database.
- [Pages and layouts](https://docs.manh.run/en/getting-started/pages-layouts.md): Each page.tsx is a page at the URL of its folder; layout.tsx wraps the pages below it and layouts nest from the root down.
- [Styling](https://docs.manh.run/en/getting-started/styling.md): Screens are built from antd and pro-components, arranged with Tailwind classes in className, and take their colors and radius from the app theme in app/theme.tsx.
- [Telegram bot](https://docs.manh.run/en/getting-started/telegram.md): An app messages its users through the app owner's own Telegram bot, receives messages and button presses in a *.telegram.ts file, and sends messages with buttons through manh/telegram.

## Structure (one page per convention file)

- [*.agent.ts](https://docs.manh.run/en/structure/agent.md): An AI assistant that chats with your users and works through the app's own tools. Changes to data wait for the user's approval. Every conversation is saved and picks up where it stopped.
- [The app/ directory](https://docs.manh.run/en/structure/app.md): All of an app's code lives in app/. Each file's path, name and extension tell manh.run whether it is a page, an API, a job or configuration.
- [auth.ts](https://docs.manh.run/en/structure/auth-config.md): app/auth.ts turns on sign-in for the app with a few lines of configuration. From it manh.run generates the users table, the sign-in API and the user management page.
- [<resource>-columns.tsx](https://docs.manh.run/en/structure/columns.md): <resource>-columns.tsx declares a resource's columns once, shared by the ProTable list, the BetaSchemaForm form and the ProDescriptions detail view.
- [components/](https://docs.manh.run/en/structure/components.md): The app/components/ folder holds UI components used on two or more pages, run in the browser.
- [*.cron.ts](https://docs.manh.run/en/structure/cron.md): Each *.cron.ts file is a job manh.run runs on a schedule, with nobody opening the app, written as a 5-field cron expression in UTC.
- [*.email.ts](https://docs.manh.run/en/structure/email.md): Each *.email.ts file gives the app its own e-mail address; mail sent there reaches the file's default function with sender, body and attachments already parsed.
- [Generated files](https://docs.manh.run/en/structure/generated.md): app/db.ts, app/api.ts and app/hooks.ts are regenerated by manh.run on every build. You import them but never write or edit them.
- [get.ts, post.ts, put.ts, patch.ts, delete.ts](https://docs.manh.run/en/structure/handlers.md): Each get.ts, post.ts, put.ts, patch.ts or delete.ts file is an API endpoint for that method, at the path of its folder.
- [*.job.ts](https://docs.manh.run/en/structure/job.md): Each *.job.ts file is a background job. Server code queues it with enqueue, and manh.run runs it later and retries it on failure.
- [layout.tsx](https://docs.manh.run/en/structure/layout.md): layout.tsx wraps every page in its folder and below, and must render <Outlet /> so the inner page shows.
- [lib/](https://docs.manh.run/en/structure/lib.md): The app/lib/ folder holds constants and helpers for one side only; .ts files run on the server, .tsx files run in the browser.
- [middleware.ts](https://docs.manh.run/en/structure/middleware.md): middleware.ts runs before every handler in its folder and below, and can set access for the whole folder.
- [page.tsx](https://docs.manh.run/en/structure/page.md): page.tsx is a page of the app, shown at the URL of its folder and run in the browser.
- [Processes (*.bpmn, DMN)](https://docs.manh.run/en/structure/process.md): Business work that spans several steps and waits — timers, events, people approving. Draw it in BPMN (Camunda flavour), decide by the numbers with a DMN table; manh.run keeps its state and resumes it on time.
- [repository.ts](https://docs.manh.run/en/structure/repository.md): repository.ts holds every database call and business rule of one resource, so handlers, cron jobs and mail handlers all call one place.
- [shared/](https://docs.manh.run/en/structure/shared.md): The app/shared/ folder holds the types, constants, enums, status lifecycles and pure functions that both pages and the server need, written once.
- [<resource>.table.ts](https://docs.manh.run/en/structure/table.md): Each <resource>.table.ts file declares one table in the app's own SQLite database, written with Drizzle, and manh.run creates it on deploy.
- [*.telegram.ts](https://docs.manh.run/en/structure/telegram.md): The *.telegram.ts file receives every message, button press and Start tap sent to the app's Telegram bot; each app has exactly one.
- [theme.tsx](https://docs.manh.run/en/structure/theme.md): app/theme.tsx holds the app's look (primary color, radius, density, dark mode, icon set, antd tokens) in one APP_THEME object the owner can edit.
- [upstream.ts](https://docs.manh.run/en/structure/upstream.md): app/upstream.ts puts the app in front of an existing API; requests with no handler are forwarded to the real system and recorded in the traffic log.
- [*.workflow.ts](https://docs.manh.run/en/structure/workflow.md): A technical chain of steps written in code, running durably on the same process engine: step.run runs once and remembers its result, step.sleep and step.waitFor wait without using resources.

## Guide

- [Reading check errors](https://docs.manh.run/en/guide/agents/check-errors.md): Each check error line has a layer, a rule id, a file and a line; this page explains the common ones and how to get an agent out of a fix loop.
- [llms.txt and Markdown copies](https://docs.manh.run/en/guide/agents/llms.md): Every docs page has a Markdown copy for agents, /llms.txt lists every page, and /llms-full.txt puts the whole English docs in one file.
- [Briefing the agent](https://docs.manh.run/en/guide/agents/prompting.md): Write the brief in business terms, let the agent write a spec first and wait for your review, then build part by part with a check after each part.
- [Data and security](https://docs.manh.run/en/guide/concepts/data-security.md): App data lives in the app's own SQLite database, secrets are readable only on the server, sign-in uses email/password or Google with a JWT, and app content never runs on the dashboard's address.
- [How manh.run works](https://docs.manh.run/en/guide/concepts/how-it-works.md): 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.
- [Why the stack is fixed](https://docs.manh.run/en/guide/concepts/locked-stack.md): Every manh.run app uses the same stack (antd and pro-components for the UI; Hono, Drizzle and SQLite for the API), so agents write better code, screens look like a product and built-in services work with no setup.
- [Build a CRUD feature](https://docs.manh.run/en/guide/recipes/crud.md): Build a complete create, read, update and delete feature for orders, with a database table, repository, API handlers, a list page and a detail page.
- [Use your data on Supabase](https://docs.manh.run/en/guide/recipes/supabase.md): Connect your Supabase project by signing in and allowing access, so the app reads and writes the data you already keep there, with no keys to paste.
- [Call outside APIs](https://docs.manh.run/en/guide/recipes/upstream.md): Call another system's API from server code, put your app in front of an existing API, change or mock single endpoints and see a log of every request.
- [Troubleshooting](https://docs.manh.run/en/guide/troubleshooting.md): Common problems when building apps on manh.run, from a blank preview, import errors and 401 after deploy to cron jobs that never run and e-mail that never arrives, with causes and fixes.
- [Diagrams, kanban, AI chat](https://docs.manh.run/en/guide/ui/advanced.md): Screens beyond tables and forms, built with libraries already in your app: edit a process as a diagram, view an org chart, drag cards on a kanban board, chat with AI.
- [APIs to know](https://docs.manh.run/en/guide/ui/api.md): The pro-components 2.8.10 props that are most often used wrong: ProTable, forms in a Modal or Drawer, valueType, and valueEnum.
- [Sign-in and sign-up](https://docs.manh.run/en/guide/ui/auth.md): Sign-in and sign-up pages use LoginForm, call the login API manh.run generates from app/auth.ts, store the session with signIn, show the Google button and show server errors on the form.
- [Business screens](https://docs.manh.run/en/guide/ui/business.md): Five complete screens by trade that run in the page, with code and an agent prompt: executive dashboard, order board, appointment calendar, point of sale, receivables.
- [Dashboards](https://docs.manh.run/en/guide/ui/dashboards.md): A dashboard shows each role its to-do list and a few key numbers at a glance, built with StatRow, ProCard, ProList, and @ant-design/charts.
- [Detail pages](https://docs.manh.run/en/guide/ui/detail.md): A detail page shows one record (a summary in the header, approval progress, details, history) and only the buttons the signed-in role can use in the current status.
- [Forms](https://docs.manh.run/en/guide/ui/forms.md): Forms that create and edit records: choose between DrawerForm, ModalForm, StepsForm, and an on-page ProForm, format money and dates, add line items, and show server errors.
- [UI playbook](https://docs.manh.run/en/guide/ui.md): The UI playbook shows how to make Manh app screens look like real products: use the right Pro component for each job and follow six shared rules.
- [App shell and page header](https://docs.manh.run/en/guide/ui/layout.md): Build the app shell with AppShell (menu per role, account, sign-out) and the top of each page with PageContainer (title, status, summary, key number, decision buttons).
- [List pages](https://docs.manh.run/en/guide/ui/lists.md): A list page shows many records, lets users search, filter by status, and select several rows to act on at once, built with ProTable.
- [Pick a component by job](https://docs.manh.run/en/guide/ui/pick.md): A lookup for choosing components: what the user does on the screen, which antd, pro-components, charts, or antd X component to use, which props to set, and which mistake to avoid.
- [Page recipes](https://docs.manh.run/en/guide/ui/recipes.md): How to combine components for common page types (dashboards, lists, long forms, settings, result pages) following ant-design-pro layouts, plus the old prop names to replace.

## API

- [check rules](https://docs.manh.run/en/api/check-rules.md): The check tool validates a project in four layers — syntax, code gate, contract rules, typecheck; this page covers when it runs, when it blocks a deploy, and the main rules by area.
- [AppShell](https://docs.manh.run/en/api/components/app-shell.md): The staff app frame from manh/shell. A menu filtered by role, sign-out, Vietnamese for every component, the app's theme and API errors shown by themselves. app/layout.tsx only declares the menu.
- [ResourceDetail](https://docs.manh.run/en/api/components/resource-detail.md): One record's page from manh/shell. A title with the status tag, the fields from the columns, buttons for the moves the signed-in role may make, edit, delete and tabs.
- [ResourceList](https://docs.manh.run/en/api/components/resource-list.md): A resource's list screen from manh/shell, declared with one set of columns. Status tabs with counts, server-side search and paging, a create form and a link to the detail page.
- [Error codes](https://docs.manh.run/en/api/errors.md): The error codes you and your agent meet on manh.run, from the app's API responses, check rule ids and deploy errors, with what each means and how to fix it.
- [apiErrorText](https://docs.manh.run/en/api/hooks/api-error-text.md): Gets the message to show for a failed API call. The server's Vietnamese message when there is one, a connection message when the server can't be reached, or a fallback.
- [setAuthToken, getAuthToken](https://docs.manh.run/en/api/hooks/auth-token.md): Two low-level functions that write and read the JWT sent with every API call. You usually use signIn and signOut instead.
- [getUser](https://docs.manh.run/en/api/hooks/get-user.md): Reads the signed-in user outside a React component. Inside a component, use useSession so the UI updates by itself.
- [optionsFrom](https://docs.manh.run/en/api/hooks/options-from.md): Turns a list endpoint into options for a Select or ProFormSelect, with search on what the user types. Use it for customer, staff and product pickers.
- [signIn, signInWith](https://docs.manh.run/en/api/hooks/sign-in.md): signIn stores the token and the user after sign-in. signInWith opens a Google sign-in window and calls signIn when it finishes.
- [signOut](https://docs.manh.run/en/api/hooks/sign-out.md): Signs the user out in the UI. Clears the stored token and user, then tells every useSession to re-render.
- [submit](https://docs.manh.run/en/api/hooks/submit.md): The onFinish handler for ProForm, ModalForm and DrawerForm. It calls the API, says it worked, reloads the table, puts server errors on the right fields and resolves true or false.
- [tableRequest, rowsOf](https://docs.manh.run/en/api/hooks/table-request.md): tableRequest connects a hand-written ProTable to a list endpoint, with paging, sorting, filters and the search box. rowsOf reads { data, total } from either an array or a page.
- [useAction](https://docs.manh.run/en/api/hooks/use-action.md): Hook that wraps a write or any other action from the UI. Calls the API, shows the result, reloads the table and resolves true or false for forms.
- [useApiClient](https://docs.manh.run/en/api/hooks/use-api-client.md): Hook that returns a typed client for your app's own API, generated from the handler files. Each function returns exactly what the handler returned.
- [useApi](https://docs.manh.run/en/api/hooks/use-api.md): Hook that returns a raw axios instance for calling APIs outside your app by absolute URL. For your app's own API, use useApiClient.
- [useLive](https://docs.manh.run/en/api/hooks/use-live.md): Hook that listens to one of your app's realtime channels and calls your function whenever the server sends a broadcast. Reconnects by itself.
- [useRequest](https://docs.manh.run/en/api/hooks/use-request.md): Hook that calls an async function when the component mounts and keeps data, loading and error for rendering. Comes with run, refresh and mutate.
- [useRoutes](https://docs.manh.run/en/api/hooks/use-routes.md): Hook that returns the list of your app's pages (path and name) for building menus. Not the react-router-dom hook of the same name.
- [useSession](https://docs.manh.run/en/api/hooks/use-session.md): Hook that returns the signed-in user and a hasRole function for role checks. The component re-renders on every sign-in and sign-out.
- [Plan limits](https://docs.manh.run/en/api/limits.md): The limits of the Free, Builder and Agency plans for projects, requests, database and file storage size, email, AI, cron and custom domains.
- [db](https://docs.manh.run/en/api/server/db.md): The Drizzle client for your app's own SQLite database, imported from app/db together with table builders and query operators. Server code (.ts) only.
- [defineEnum](https://docs.manh.run/en/api/server/define-enum.md): Declare a list of statuses or categories once, with labels and colours, and use it in schemas, emails, tables, selects and badges.
- [defineFlow](https://docs.manh.run/en/api/server/define-flow.md): Declare a record's lifecycle once, covering which status may move where and which roles may move it. The server blocks illegal moves, the UI shows only legal buttons.
- [env](https://docs.manh.run/en/api/server/env.md): The object holding your app's secrets and settings, imported from manh/env. Server code (.ts) only.
- [listSchema, listOf](https://docs.manh.run/en/api/server/list-of.md): listSchema validates a list API's query (page, search, filters, sort). listOf runs that query against a table and returns { data, total }.
- [schemaOf](https://docs.manh.run/en/api/server/schema-of.md): Builds zod schemas for create and update bodies from a table's columns, so a handler doesn't redeclare every field.
- [blob](https://docs.manh.run/en/api/std/blob.md): Store, read, list and share files in your app's own folder with manh/blob, including expiring signed links for uploads and downloads.
- [email](https://docs.manh.run/en/api/std/email.md): Send email from your app's server code with manh/email, no API key needed. Comes with html for safe interpolation and mailFrame for a ready-made layout. Receiving mail is done by *.email.ts files.
- [enqueue](https://docs.manh.run/en/api/std/jobs.md): Queue slow work to run later in a *.job.ts file, with retries on failure. The request answers at once instead of waiting.
- [OpenAI](https://docs.manh.run/en/api/std/openai.md): Call AI from your app's server code with manh/openai. Same calls as the official openai SDK, no API key needed.
- [pdf](https://docs.manh.run/en/api/std/pdf.md): Makes Vietnamese PDF files from server code with manh/pdf, for repair slips, quotes, delivery notes and warranty slips. The built-in font prints every Vietnamese letter and the ₫ sign.
- [broadcast](https://docs.manh.run/en/api/std/realtime.md): Send a realtime message from server code to every page listening on that channel with useLive, so screens update when data changes.
- [telegram](https://docs.manh.run/en/api/std/telegram.md): Send messages with buttons through your app's own Telegram bot with manh/telegram, and create the link that lets a user receive them. Incoming messages and button presses go to a *.telegram.ts file.
- [Feature blocks](https://docs.manh.run/en/api/tools/blocks.md): Three tools, blocks, block_plan and block_add, let the agent find tested ready-made features, preview what a block adds, then copy it into app/ as the app's own code.
- [check](https://docs.manh.run/en/api/tools/check.md): The check tool validates a project against the Manh framework conventions, from syntax to TypeScript types, and returns each error with its file, line and fix; deploys are refused while it reports errors.
- [Checkpoints](https://docs.manh.run/en/api/tools/checkpoints.md): Two tools, checkpoint and restore_checkpoint, let the agent save the project's file tree under a label and put the files back to a saved version; restoring does not change the running app.
- [Cron](https://docs.manh.run/en/api/tools/cron.md): Three tools, cron_jobs, cron_runs and cron_control, let the agent list deployed scheduled jobs, read their run history, run a job now, pause it or resume its schedule.
- [Database](https://docs.manh.run/en/api/tools/db.md): Two tools, db_query and db_exec, let the agent read and write the app's own SQLite database, one SQL statement per call; this is the running app's real data and it has no backup.
- [deploy](https://docs.manh.run/en/api/tools/deploy.md): The deploy tool runs check, builds the UI and the backend, updates the schema and puts the UI and the API live at the app's address together; it is the only call that changes the running app.
- [Secrets](https://docs.manh.run/en/api/tools/env.md): Two tools, env_set and env_list, let the agent store API keys and tokens of outside services for the app's backend; values are never returned to the agent.
- [Files](https://docs.manh.run/en/api/tools/files.md): Four tools, list_files, read_files, write_files and delete_files, read and write the app/ tree; each write is all-or-nothing, saves an automatic copy and returns a check result.
- [framework_docs](https://docs.manh.run/en/api/tools/framework-docs.md): The framework_docs tool returns the Manh framework docs to the agent by topic, from the spec process to file conventions, UI, backend and deploy, readable one section at a time.
- [Images](https://docs.manh.run/en/api/tools/images.md): Two tools, list_images and upload_image, let the agent use your own photos on the app's website, from photos you uploaded or from links and files you send in the chat.
- [Agent tools](https://docs.manh.run/en/api/tools.md): Your agent builds apps on manh.run through MCP tools; this page lists each group of tools, the two tool sets by connection URL and the order an agent calls them in a build session.
- [Outside data](https://docs.manh.run/en/api/tools/integrations.md): Two tools, integrations and integration_sql, let the agent see the Supabase project you connected to the app, read its tables and run SQL on it; full tool set only.
- [logs](https://docs.manh.run/en/api/tools/logs.md): The logs tool shows the agent recent requests, backend console output, the app's traffic log and a metrics summary, to find errors and test flows after a deploy.
- [Projects](https://docs.manh.run/en/api/tools/projects.md): Three tools, list_projects, create_project and get_project, let the agent list your projects, create one from a starter or an example app, and read a project's state.
- [Testing](https://docs.manh.run/en/api/tools/testing.md): Three tools, run_acceptance, create_test_accounts and remove_test_accounts, let the agent run business tests on a test copy of the app and try each role with throw-away accounts.
- [Versions](https://docs.manh.run/en/api/versions.md): The exact version of every library in manh.run's locked stack, how new versions reach deployed apps, and recent framework changes that affect how apps are written.

## Deploy

- [Custom domain](https://docs.manh.run/en/deploy/domains.md): Point a subdomain you own, such as app.example.com, at a deployed app so its users see only your domain. Available from the Builder plan, 1 domain per project.
- [Deploy an app](https://docs.manh.run/en/deploy.md): Deploy runs check on the project, then puts the app's UI and API live on the app's address together. Writing files never deploys the app.
- [Logs and traffic](https://docs.manh.run/en/deploy/logs.md): The Operations section shows how a deployed app behaves, with totals, every API request, and the log lines of handlers and cron jobs; agents read the same data with the logs tool.
- [Rollback and checkpoints](https://docs.manh.run/en/deploy/rollback.md): A checkpoint saves the project's whole file tree; from the Deploys & history section you switch the app back to an earlier build in seconds, or restore a checkpoint and deploy it.

## Examples

- [Live examples](https://docs.manh.run/en/examples.md): Business screens built on Manh, running right in the page with mock data; open the Code tab to see the file and the Agent prompt tab to see what the agent was asked.
- [UI templates](https://docs.manh.run/en/examples/ui.md): The screen frames agents use most (app shell, lists, dashboards, forms, details, sign-in, diagrams), running in the page with mock data, with the code and a Playground link to edit them.

## Optional

- [Vietnamese docs](https://manh.run/docs.md): the same pages in Vietnamese, at the same paths without /en.
- [Pricing](https://manh.run/pricing): Free, Builder, Agency — no token billing, no per-end-user pricing.
- [Showcase](https://manh.run/showcase): apps running on manh.run.
