Create an App

Everything in App Builder starts on the App Builder home page, the catalog of your tenant's apps. From here you create a new app from scratch or import an existing repository. Either path provisions a fresh sandbox and drops you into the editor with a running preview.

The App Builder home page

Open App Builder from the navigation. The page is titled App Builder ("Build and manage apps powered by AI") and lists your apps as cards — or as rows, via the grid/list toggle. A filter bar across the top lets you narrow the list:

Search — case-insensitive substring match on the app name.
State — Any state (the default), Drafts, or Published. Archived apps are excluded from the list regardless of this filter.
Owner — My apps (the default) or All apps in the tenant.
Sort — Last edited (the default), Date created, or Name.

The first two tiles are always Create new app ("Describe an idea and the AI builds it") and Import from GitHub ("Bring an existing Node.js repo into the builder"). Each app tile shows its name, category, deployment status badge, and — once published — a View live action.

Create a new app

Select the Create new app tile. The builder immediately:

Creates a catalog entry for the app, named Untitled App until you (or the AI) rename it.
Creates the app's editor session and provisions an ephemeral sandbox from a warm pool.
Copies the starter template — a Vite + React 19 + Hono project with its dependencies pre-installed — into the workspace.
Boots the dev server and initializes a git repository for the app.

You're navigated straight into the editor while this runs. The new-app flow uses the blank starter template; there is no template picker today.

You don't name the app up front. The AI auto-names it from your first few messages, and you can rename it any time from the editor's App settings or the home page. The app's public URL slug tracks the name until first publish, then locks — see The app URL.

Provisioning stages

Provisioning runs asynchronously and the editor shows a stepper ("Setting up your app…") while it completes. The stages, in order:

Stage	What's happening
Setting up workspace	A sandbox is claimed from the warm pool and the workspace is prepared.
Installing dependencies	The template source and its pre-installed dependencies are copied into `/workspace`.
Starting dev server	The Vite front end and Hono back end are started.
Initializing repository	A git repository is created in the workspace and the initial commit is made.
Waiting for preview	The builder polls the live preview URL until it responds, then the session flips to ready.

When provisioning finishes, the preview renders the starter app and the chat is ready for your first message.

Import an existing repo

If you already have an app — built locally with the Ema starter or shared by a teammate — import it instead of starting over. Select Import from GitHub, paste the repository URL, and the builder clones it into a sandbox, installs dependencies, starts the dev server, and creates a fresh private repo under the Ema organization with your cloned history pushed in. Your source repo is not modified.

Imports must match the starter shape. Only Vite + Hono apps that match the App Builder template shape can be imported. Concretely, the repo must:

Have a package.json at the repository root.
List @vitejs/plugin-react in its dependencies — the canonical Vite signal. (The template pulls Vite in through this plugin rather than listing vite directly, so a bare vite dependency is not enough on its own.)
List both hono and @hono/node-server — the framework and its Node runtime. One without the other is rejected.
Contain a server/index.ts Hono back-end entry point.

The URL format and a duplicate-import check run synchronously before anything is created, so a malformed URL or an already-imported repo fails immediately in the dialog and leaves nothing behind. The Vite + Hono shape itself is verified after the repo is cloned into the sandbox; a non-conforming repo surfaces a specific reason (which dependency or file is missing) and the import fails without producing a usable app.

What the URL looks like

The import dialog expects an HTTPS GitHub URL of the form https://github.com/<owner>/<repo>, for example https://github.com/Ema-Unlimited/magnit. The repo must be readable by the Ema GitHub App.

Import provisioning stages

Imports go through the same progress UI, with stages: cloning → installing → starting → ready. The dev server starts on a fixed preview port regardless of what the repo's own scripts hardcode, so a freshly imported app behaves the same as a newly created one once it's running.

Common import errors

The import dialog surfaces the specific reason an import was rejected. The most common:

Message	Cause and fix
We couldn't find that repo, or the Ema GitHub App can't access it.	The URL is wrong, the repo is private and not shared with the Ema GitHub App, or it doesn't exist. Confirm the URL and the app's access.
We couldn't find a package.json at the repo root. Only Vite + Hono apps with a package.json can be imported.	The repo has no `package.json` at its root, so it isn't a Node.js project the builder can run.
Only Vite + Hono apps can be imported. This repo uses a different framework.	Neither `vite` nor `@vitejs/plugin-react` is in the repo's dependencies, so the builder doesn't recognize it as a Vite project.
This repo's package.json doesn't list @vitejs/plugin-react — required for the Vite + React template shape.	The repo looks Vite-ish but is missing `@vitejs/plugin-react`, the plugin the template's front end is built on. Add it.
This repo's package.json doesn't list hono and @hono/node-server — both are required for the template shape.	One or both of the Hono packages are missing. Add both `hono` and `@hono/node-server`.
This repo is missing a Hono backend at server/index.ts.	The Hono dependencies are present but there's no `server/index.ts` entry point for the builder to start.
This repo is already imported as "<name>".	The same source repo is already an app in this tenant. Open that app, or permanently delete it before re-importing.

Imported apps push back to their source. When you connect an imported app to GitHub, edits flow back into your original repository rather than a new fork — provided the source lives in an org the builder's write token can reach. Template-created apps always get a fresh private repo instead, since there's no source to push back to. See GitHub sync.

What's next

The App Editor — build your app once the sandbox is ready.
Deploying and Versioning — publish the app to a hosted URL.