# Create an App: Genaro Apps for coding agents > Build your own tools that run inside Genaro. This is the plain-text twin of https://genaro.ai/docs/apps, written for coding agents. The SDK ships the complete reference in `node_modules/@genaro/apps-sdk/README.md` and `docs/`; read it once the project exists. ## Start here An app is a tool you build that runs inside Genaro. You decide what it does and what information it needs. When you publish it, it shows up in Genaro as a simple form. A user fills in the form, presses run, and the app does the rest. Anyone in your Workspace can run it the same way, and programs and agents can start it over the REST API or MCP. ## Publish from source: the quickest path for agents An agent connected to Genaro over MCP (`https://api.genaro.ai/mcp`) or the REST API needs no install and no build step. Write the App as TypeScript, then send it to the MCP tool `genaro_publish_app` (or `POST https://api.genaro.ai/api/v1/apps`, same body) as `source`, one file, or as `files`, a map of relative path to text with `entry` naming the file that default-exports `defineApp(...)`. Genaro builds the bundle itself, with the same esbuild settings as `genaro-app build` and the `@genaro/apps-sdk` version this server ships, then publishes it like any other version. The key needs `content:write`; publishing is free. ```text # One file: the MCP tool genaro_publish_app (or POST /api/v1/apps, same body) { "name": "Clothing Labeler", "source": "import { defineApp, t } from \"@genaro/apps-sdk\"\n\nexport default defineApp({ ... })\n" } # Several files: name the one that default-exports the App { "name": "Clothing Labeler", "entry": "app.ts", "files": { "app.ts": "import { defineApp, t } from \"@genaro/apps-sdk\"\nimport { labelPrompt } from \"./prompts\"\n...", "prompts.ts": "export function labelPrompt(text: string): string { ... }\n" } } # Source that does not build publishes nothing and says where (422) { "error": { "type": "app_build_failed", "message": "The source did not build, so nothing was published: prompts.ts:3:1: Unexpected end of file", "diagnostics": [ { "file": "prompts.ts", "line": 3, "column": 1, "message": "Unexpected end of file" } ] } } ``` - Import only `@genaro/apps-sdk` and the App's own files by relative path (`./prompts`). npm packages and Node built-ins are refused at the import. - Files are `.ts`, `.js` or `.json`: at most 50, 1 MiB in total. Build configuration (`package.json`, `tsconfig.json`) is Genaro's own. - Source that does not build publishes nothing. The error is `app_build_failed` with `error.diagnostics`: file, line, column and message for each problem. Fix them and publish again. - Types are not checked on the server, only syntax and imports. A type mistake surfaces when the run reaches it, so typecheck first if you have `tsc`. - Publishing identical source again reuses the version. The bundle, its source map and your files are stored with the version, so the console and run traces show your TypeScript. Everything below about writing Apps applies unchanged. The CLI path that follows adds local typechecking and `genaro-app validate`, a free dry run, for people with a Genaro checkout. ## Getting started The easiest way to build an App is to give the prompt below to a coding agent. It checks the tools on the computer, creates a starter project, and follows the current Genaro instructions included with the SDK. Prompt for your coding agent: ```text Help me build an App for Genaro. First, check whether this computer has Node.js 22 or newer, npm and pnpm. If any is missing, explain what needs to be installed and ask for my permission before installing it from nodejs.org or a trusted system package manager. The Genaro Apps SDK is installed from a Genaro checkout. Ask me where mine is, then install it in this folder: (cd /path/to/genaro/sdk/apps && pnpm install && pnpm build) npm install --save /path/to/genaro/sdk/apps # in your App project Ask me what I want the App to do and what to call the project folder. Then run: npx genaro-app create --yes Open the generated project and read AGENTS.md before writing code. Never ask me to paste a Genaro API key into this chat or put one in source code. Building and validating do not need a key. When I explicitly ask to publish or start a real run, tell me to run `npx genaro-app configure` myself inside the project. Implement the App, keep t.object at the input and output roots only, update input.example.json, then run `npm run check` and `npm run validate`. Show me any decisions you need from me and summarize the validation result. ``` Or create the project yourself: ```bash (cd /path/to/genaro/sdk/apps && pnpm install && pnpm build) npm install --save /path/to/genaro/sdk/apps # in your App project npx genaro-app create ``` The `@genaro/apps-sdk` package is not on npm yet, so it is installed from a Genaro checkout as above. Node 22 or newer is required. `genaro-app create` scaffolds a standalone project whose `AGENTS.md` points at the installed SDK reference. No API key is needed to build or validate. ### Create your API key This is the one setup step the person must complete themselves. In the Genaro console, open API keys (https://genaro.ai/console/api-keys) and create a Workspace API key. The full key is shown once. It is not needed to build or validate. When they are ready to publish or start a real run, they personally run `npx genaro-app configure` inside the project and paste it there. It is saved in the Git-ignored `.genaro-app.json`. - `read`: find published Apps, follow run progress, read results and traces. - `content:write`: publish Apps and new versions. - `generate`: start real runs and answer review steps. Select all three scopes to publish and test a real run with the same key. Starting a run authorizes the published App to perform its documented actions, charged under the key's model allow-list and spend cap. Treat the key like a password. Never ask the person to paste it into agent chat, and never put it in App code or source control. In automation, `GENARO_API_KEY` replaces `configure`. ## How Apps work | | Inputs | Execution | Outputs | | --- | --- | --- | --- | | Concept | What it needs | Your process | What it returns | | Definition | Schema | Code, no fixed schema | Schema | | Surface | A form in the console | The App runs its steps | Results: Assets and values | | Location | Genaro console | Secure sandbox (QuickJS in WebAssembly) | Asset system, saved and reusable | | Possible shapes | One or many fields | Branch, parallel, wait | One or many results | Apps are for creative work that you repeat. An App can generate images, use photos from the Workspace's Assets, create several versions at once, and stop to let a person pick the best one before it continues. A run can wait hours or days for that decision, and it never loses its place. If the same steps are followed every time a certain kind of image is produced, an App can capture those steps once and run them from then on. - Work in parallel: one concept fans out into several generations that run at the same time. - Put judgment in the middle: the App can pause after creating options, ask a person to choose, then continue using that choice. - Wait without losing progress: ordinary code has to keep running until it finishes. An App can suspend while it waits, then resume later from the same place. An App is a small TypeScript program you publish to Genaro. That program defines the form people fill in, the steps that run when they press run, and the result that comes back. ## Anatomy of an app Every App tells Genaro four things: what it is called (the listing: slug, name and description), what it needs (inputs), what it does (execution), and what it returns (outputs). ## The interface The `input` section of an App defines the input form. Genaro reads each field, builds the matching form control, checks the answers, and passes them to the code. There is no separate form to design or keep in sync. The same rules are enforced however a run starts: from the console, the API, MCP or the CLI. ```ts input: t.object({ title: t.string({ label: "Title", placeholder: "Summer campaign", description: "Give this run a name.", maxLength: 80 }), notes: t.string({ label: "Notes", multiline: true, maxLength: 1000 }), versions: t.number({ label: "Versions", integer: true, min: 1, max: 4 }), quality: t.number({ label: "Quality", min: 0, max: 100 }), transparent: t.boolean({ label: "Transparent background" }), format: t.enum(["Square", "Portrait", "Landscape"] as const, { label: "Format", placeholder: "Choose a format" }), tags: t.array(t.string(), { label: "Tags", description: "Add one tag per line." }), image: t.asset("image", { label: "Source image" }), video: t.asset("video", { label: "Source video" }) }) ``` The field key becomes the property the code reads: `title` becomes `input.title`. The `label` supplies the words people see. A `placeholder` gives an example inside an empty control, and a `description` adds guidance beneath it. The field type and its other options determine which control Genaro renders and how it behaves. ## What your App can access An App can read its form inputs and use a small set of actions built into Genaro. Today those actions include generating media, describing images and video and calling text models, reading the Workspace's assets and groups, adding an asset to a group, asking someone to review work, naming the work for the run's execution trace, and getting recorded random values or timestamps. In the code, these actions are grouped under a value named `ctx`. - Built-in actions do the work: media, language models, groups, choices, and recorded values. - Use TypeScript for logic: loop, branch on a condition, retry a failed step, and perform steps in whatever order the work requires. - Web requests, outside APIs, local files and any other action are outside the runtime. ## Your first App This App takes a photo and a line of text, and it prints that text onto the person's clothing. It is the smallest App worth writing, and it still travels the whole path from the input form to a finished image in the Workspace. ```ts import { defineApp, t } from "@genaro/apps-sdk" export default defineApp({ // 1 slug: "clothing-labeler", name: "Clothing Labeler", description: "Print custom text onto a person's clothing", input: t.object({ // 2 person: t.asset("image", { label: "Person photo" }), text: t.string({ label: "Text to print" }) }), output: t.object({ image: t.asset("image") }), async run(ctx, input) { const result = await ctx.generate.image({ // 3 model: "krea2", references: [input.person], prompt: `Keep the same person and outfit, but print "${input.text}" ` + `clearly on the front of the clothing` }) return { image: result.assetId } // 4 } }) ``` 1. `defineApp` declares the App. It gives Genaro the name, the description, the shape of the form, and the code to run. Every App calls it once, as the file's default export. 2. `t.object` wraps all the fields. Use it once at the input root and once at the output root; it cannot be nested inside another field or inside `t.array`. 3. `ctx.generate.image` asks Genaro to create one image. This is the step you pay for, and the App automatically waits until the image is ready. Because this call passes references, it runs `krea-2-edit` over the selected photo instead of painting a new person from scratch. 4. `return` hands back what the App produced. Genaro shows the returned image when the run finishes. An image field takes the ID of an Asset in the Workspace. Above, `input.person` is passed directly to `references` so the generation uses the photo that person selected. ## Waiting happens automatically A generation may take time. A person may not answer a choice until tomorrow. When something is not ready, Genaro automatically suspends the App and waits, using no compute. As soon as the result or response is ready, the App continues from the same place. You do not need to manage the waiting yourself. App code interacts with the outside world only through actions Genaro provides. Those actions record what happened before the App waits, which is what lets the run continue safely from the same place later. Keep the ordinary code between `ctx` calls deterministic: no `Math.random()`, `Date.now()`, `fetch`, or mutable global state. Pass only plain JSON to `ctx`, and await every `ctx` call before returning. Every run has a budget of 200 passes. Each `ctx` call awaited in sequence costs one; calls started together and awaited with one `Promise.all` share a single pass. ## Pause for human review Some decisions need a person, not another automated step. Add a review wherever someone should approve the work, choose a direction, or check the details before the App moves on. Genaro suspends the App until the review is complete, then continues with the answer. Reviews are answered in the console (Apps › Reviews, or on the run's page), with `POST /api/v1/app_reviews/{app_review_id}/resolve`, or with the MCP tool `genaro_resolve_app_review`, using a key with `generate`. Approval (`approval`): one go or no-go decision for a deliverable, launch, or handoff. Returns `{ decision: "approved" | "rejected" }`. ```ts const approval = await ctx.review.approval({ title: "Approve this campaign", subjects: imageOptions, approveLabel: "Ready for client", rejectLabel: "Keep working" }) ``` Select one (`selectOne`): choose exactly one direction from a set of options. Returns one option value. ```ts const heroId = await ctx.review.selectOne({ title: "Choose the hero image", options: imageOptions }) ``` Select many (`selectMany`): build one shortlist; set a minimum and maximum to control its size. Returns a list of option values. ```ts const shortlist = await ctx.review.selectMany({ title: "Build the client shortlist", options: imageOptions, min: 2, max: 3 }) ``` QA checklist (`checklist`): check every named criterion with Pass, Fail, or an allowed N/A. Returns one result per criterion. ```ts const qa = await ctx.review.checklist({ title: "Complete preflight QA", subjects: imageOptions, criteria: [ { id: "brand", label: "Matches the brand direction" }, { id: "copy", label: "All visible copy is accurate" }, { id: "legal", label: "Required legal copy is present", allowNotApplicable: true } ] }) ``` Review each (`reviewEach`): give every item its own decision and add feedback when changes are needed. Returns one decision per item, with feedback keyed by item ID for every `"changes_requested"`. ```ts const review = await ctx.review.reviewEach({ title: "Review every campaign asset", items: imageOptions.map((option) => ({ id: option.value, label: option.label, assetId: option.assetId })) }) ``` ## Inputs and outputs Every App declares a schema for what it takes in and a schema for what it gives back. Each line in the input schema creates one control in the form people fill in before they press run. The same schema gives the code its TypeScript types. Every field is required unless built with `optional: true`, in which case it may be left blank and the code sees `undefined`. | Schema line | Type | Control people see | | --- | --- | --- | | `t.string` | `string` | Text field or textarea (`multiline: true`) | | `t.number` | `number` | Number field | | `t.boolean` | `boolean` | Checkbox | | `t.enum` | literal union | Select | | `t.array` | array | Textarea, one entry per line | | `t.asset("image" \| "video")` | asset ID | Asset ID field | | `t.object` | object | Complete form or result | `t.object` wraps the complete input or output. It is only supported at those two roots, not as a nested field or inside `t.array`. TypeScript and local validation both catch that mistake. Write labels for people, not for code. Return asset IDs from the output: the run's page shows them as previews, and they are ordinary Workspace Assets. ## Capabilities App code can use the actions Genaro deliberately provides. It cannot reach the internet, local files, secrets, or outside services directly. Keeping those boundaries explicit is what lets Genaro pause a run, resume it later, and continue under the authorization of the API key that started it. Apps can: - Create forms with typed inputs and results - Generate and edit images and generate video with any Genaro model - Read the assets and groups of the run's Workspace - Call Genaro text models for chat and image or video description (billed to the balance) - Add generated media to an existing group - Run several generation steps in parallel - Pause for approvals, selections, QA, and per-item review - Name spans of work for the run's execution trace - Use recorded time and random values when a workflow needs them - Wait for hours or days and resume from the same place App code can't: - Make arbitrary web requests or call outside APIs - Read local files, environment variables, or secrets - Use raw secrets or provider credentials - Create schedules, timers, or background triggers - Store private App data between runs - Upload assets, or create or delete groups Unknown methods are not supported and fail the App step. Use only the actions below. ## Actions your App can take Every action runs as the API key that started the run and stays inside its Workspace. Paid work is quoted, charged and attributed exactly as the same request from that key would be: its model allow-list and spend cap apply, and revoking the key stops the run before its next step. - `ctx.generate.image({ prompt, references?, model? })` → `{ generationId, assetId, assetIds }`. Paid generation. With only a prompt it generates a new image; with up to two asset IDs in `references` it edits those images. The only model name is `"krea2"`: with references it runs `krea-2-edit`, without them `krea-2` text-to-image at 1:1 and 1k. - `ctx.generate.media({ model, params, provider? })` → `{ generationId, assetId, assetIds, data? }`. Paid generation. Runs any model `GET /api/v1/models` lists, with the same `params` as `POST /api/v1/generations`. Media inputs are asset references, `{ asset_id: "..." }`, never URLs. - `ctx.media.firstFrame({ videoAssetId })` → `{ assetId }`. Free. First decoded video frame as a new image Asset. - `ctx.media.lastFrame({ videoAssetId })` → `{ assetId }`. Free. Exact final decoded frame as a new image Asset, suitable as the next clip's starting reference. - `ctx.media.stitch({ videoAssetIds })` → `{ assetId }`. Free. Join 1–16 ready videos in the supplied order into a new video Asset. Mismatched dimensions, fps and codecs are normalized to the first clip. Audio is retained only when every clip has it; otherwise the output is silent. All media derivations require `read` and `content:write`. Inputs and results belong to the run's Workspace; results have lineage to their inputs. Repeating a derivation for the same ordered inputs and byte versions reuses the Asset. No provider or ledger charge. Limits: 200 MB aggregate input, output under 200 MB, 120 seconds aggregate duration, 3840 pixels per side, 8.3 megapixels, 60 fps, three-minute processing budget and at most 60 seconds per ffmpeg process. Host commands execute after the guest exits and journal their result; they do not consume the guest's 30-second execution window. Errors reject the promise and can be caught. - `ctx.assets.get(id)` → `Asset | null`; `ctx.assets.list({ limit?, mediaKind?, source? })` → `Asset[]`. Free. - `ctx.groups.get(id)` → `Group | null`; `list({ limit? })` → `Group[]`; `items(id, { limit?, cursor? })` → `{ items, cursor, hasMore }`; `addAsset(groupId, assetId)` → `Group`. Free. Adding an asset already in the group changes nothing. - `ctx.llm.chat({ messages, model, temperature?, maxTokens?, json? })` → `{ content, model }`. Charged per call from the tokens used. `model` is a text model id from `GET /api/v1/models`. A run may make at most 30 text model calls. - `ctx.llm.describeImage({ assetId | assets, prompt, model, maxTokens?, json? })` → `{ content, model }`. Up to 8 images. - `ctx.llm.describeVideo({ assetId, prompt, model, maxTokens?, json? })` → `{ content, model }`. - `ctx.review.approval({ title, instructions?, subjects?, approveLabel?, rejectLabel? })` → `{ decision }`. - `ctx.review.selectOne({ options, title, instructions?, submit? })` → `string`. - `ctx.review.selectMany({ options, title, instructions?, min?, max? })` → `string[]`. - `ctx.review.checklist({ criteria, title, instructions?, subjects? })` → `{ results }`. - `ctx.review.reviewEach({ items, title, instructions? })` → `{ decisions, feedback }`. - `ctx.trace.span({ name, key?, attributes? }, (span) => …)` → `{ value, spanId }`. Use the `span` context inside the callback so its steps belong to the span. `ctx.trace.startSpan`, `event`, `link` and `setOutcome` are in the SDK reference. - `ctx.random()` → a number in `[0, 1)`, recorded for the run. - `ctx.now()` → epoch milliseconds, recorded for the run. Find media the Workspace already has: ```ts const images = await ctx.assets.list({ mediaKind: "image", limit: 25 }) const groups = await ctx.groups.list() const page = await ctx.groups.items(input.groupId, { limit: 25 }) ``` ## Common recipes Each recipe adds one new idea to the first App. ### Generate several versions at once The generations run at the same time, so the run waits once rather than once per image. ```ts const styles = ["watercolor", "editorial", "neon"] as const const variants = await Promise.all( styles.map((style) => ctx.generate.image({ prompt: `${input.subject}, ${style} style` }) ) ) const imageIds = variants.map((variant) => variant.assetId) ``` ### Pause for a person, then refine their choice ```ts const variants = await Promise.all( ["warm", "cool", "monochrome"].map((palette) => ctx.generate.image({ references: [input.photo], prompt: `Restyle this photo with a ${palette} palette` }) ) ) const chosenId = await ctx.review.selectOne({ options: variants.map((variant) => variant.assetId), title: "Choose the direction to refine" }) const refined = await ctx.generate.image({ references: [chosenId], prompt: "Polish this direction for a finished campaign image" }) return { image: refined.assetId } ``` ### Save a generated image to a group ```ts const result = await ctx.generate.image({ prompt: input.prompt }) await ctx.groups.addAsset( input.groupId, result.assetId ) return { image: result.assetId } ``` ### Turn an image from a group into a video ```ts const page = await ctx.groups.items(input.groupId, { limit: 25 }) const source = page.items.find((asset) => asset.mediaKind === "image") if (!source) { throw new Error("This group has no image") } const result = await ctx.generate.media({ model: "seedance-v2-fast", params: { prompt: input.motion, image: { asset_id: source.id }, duration: 5 } }) if (!result.assetId) { throw new Error("The video model returned no asset") } return { video: result.assetId } ``` ### Chain video clips, then stitch them Start from `input.firstClip` and a short list of `input.nextPrompts`. Each new clip uses the previous clip's last frame. Frame extraction and stitching are free; each generation is paid. Keep the chain within 16 clips and 120 seconds total. ```ts const clips = [input.firstClip] for (const prompt of input.nextPrompts) { const frame = await ctx.media.lastFrame({ videoAssetId: clips[clips.length - 1] }) const next = await ctx.generate.media({ model: "seedance-v2-fast", params: { prompt, image: { asset_id: frame.assetId }, duration: 5 } }) if (!next.assetId) throw new Error("The video model returned no asset") clips.push(next.assetId) } const stitched = await ctx.media.stitch({ videoAssetIds: clips }) return { video: stitched.assetId } ``` ### Branch on time or randomness safely ```ts const randomValue = await ctx.random() const startedAt = await ctx.now() const direction = randomValue < 0.5 ? "minimal" : "expressive" const result = await ctx.generate.image({ prompt: `${input.subject}, ${direction} art direction` }) return { image: result.assetId, startedAt } ``` ### Recover from a step that failed A refused Generation charges nothing; catch the error and make a simpler attempt. ```ts let assetId: string try { const primary = await ctx.generate.image({ prompt: input.ambitiousPrompt }) assetId = primary.assetId } catch { const fallback = await ctx.generate.image({ prompt: input.simplePrompt }) assetId = fallback.assetId } return { image: assetId } ``` ### Describe media with an LLM ```ts const { content: description } = await ctx.llm.describeImage({ model: input.visionModel, assetId: input.photo, prompt: "Describe wardrobe, lighting, and pose in one short paragraph." }) const { content: caption } = await ctx.llm.chat({ model: input.textModel, messages: [ { role: "system", content: "You write short social captions." }, { role: "user", content: `Write a caption for: ${description}` } ] }) return { description, caption } ``` ## Publish and run Connected over MCP or the API? Publish from source as above. With the CLI: check the App, publish it, and start one small real run. First, the person runs `npx genaro-app configure` themselves so the project has their API key without exposing it in agent chat. Publishing is free and creates a new immutable version without changing runs already in progress; publishing identical bytes or source again reuses the version. ```bash npm run check npm run validate npx genaro-app build app.ts npx genaro-app publish app.bundle.js npx genaro-app run --input input.example.json ``` `genaro-app validate` simulates the whole run with stub results: nothing is generated and nothing is charged. It prints every step, the number of paid generations and text model calls a real run would make, and the passes used. `genaro-app run` starts a real run, which can create paid generations; starting it is free, and its generations and text model calls are charged as the run reaches them. A published App also runs from its page in the console (https://genaro.ai/console/apps), where the person picks the API key the run acts for. The same operations over REST (paths under `https://api.genaro.ai/api/v1`) and MCP (`https://api.genaro.ai/mcp`): | Operation | REST | MCP tool | | --- | --- | --- | | List and get Apps | `GET /apps`, `GET /apps/{app_id}` | `genaro_list_apps`, `genaro_get_app` | | Publish from TypeScript source or a bundle | `POST /apps` | `genaro_publish_app` | | Archive an App | `POST /apps/{app_id}/archive` | `genaro_archive_app` | | Start a run | `POST /apps/{app_id}/runs` | `genaro_create_app_run` | | List and get runs | `GET /app_runs`, `GET /app_runs/{app_run_id}` | `genaro_list_app_runs`, `genaro_get_app_run` | | Read a run's execution trace | `GET /app_runs/{app_run_id}/trace` | `genaro_get_app_run_trace` | | List and get review steps | `GET /app_reviews`, `GET /app_reviews/{app_review_id}` | `genaro_list_app_reviews`, `genaro_get_app_review` | | Answer a review step | `POST /app_reviews/{app_review_id}/resolve` | `genaro_resolve_app_review` | `POST /apps` takes `{name, source}`, `{name, files, entry}` or `{name, bundle, source_map?}`; `POST /apps/{app_id}/runs` takes `{input, correlation_id?}`, and a repeated `correlation_id` returns the run already started. The OpenAPI document at https://genaro.ai/openapi.yaml has the exact shapes. ## Links - Apps primer: https://genaro.ai/docs/apps - Developer documentation: https://genaro.ai/docs - OpenAPI 3.1: https://genaro.ai/openapi.yaml - Genaro LLM map: https://genaro.ai/llms.txt