# Create an app with create-ovok

Canonical page: https://docs.ovok.com/cli/create-ovok

**Complexity:** 1 of 5 · **Clients:** Web (`@ovok/core`), React Native (`@ovok/native`) · **Time:** 5 minutes

`create-ovok` creates a workspace, installs it and makes its first git commit. Its apps already know
your Ovok API and tenant. AI coding agents in it get the Ovok rules and the Ovok MCP server.

## Set up [Console] [#set-up-console]

You need:

- Node.js 22.12 or later, and pnpm. If `pnpm --version` fails, run `corepack enable pnpm`.
- Your project's tenant code. [Find your tenant code](/authentication/project-setup), or start
  with the example tenant `public-example`.
- For the mobile app, Xcode to build for iOS or Android Studio to build for Android.

## Create the workspace [Client-side] [#create-the-workspace-client-side]

Run `create-ovok` with your project's name:

```bash
npm create ovok@latest my-app
```

It asks which apps to start with. The recommended setup is a web app and a mobile app for iOS and
Android, against `https://api.sandbox.ovok.com` and the tenant `public-example`. Choose to set each
part yourself to enter your own tenant code.

To skip the questions, answer them with flags:

```bash
npm create ovok@latest my-app -- --platform mobile-web --tenant {{TENANT_CODE}} --yes
```

- `--platform` picks the apps: `web`, `mobile` or `mobile-web`.
- `--tenant` sets the tenant code the apps send.
- `--yes` takes the recommended setup for every question no flag answered.

The [create-ovok reference](/cli/reference/create-ovok) lists every flag. With pnpm, run
`pnpm create ovok my-app`.

### Verify your integration [#verify-your-integration]

`create-ovok` ends with the next steps to run. The workspace holds:

| Path | What it holds |
| --- | --- |
| `apps/web` | A Vite and React app that signs in a practitioner and lists up to ten patients |
| `apps/mobile` | An Expo app that signs in a patient |
| `.env` | `OVOK_BASE_URL` and `OVOK_TENANT_CODE`, which every app reads |
| `.mcp.json` | The Ovok MCP server, for AI coding agents |
| `AGENTS.md`, `CLAUDE.md` | The Ovok rules, for AI coding agents |

If the install failed, the workspace stays in place. Run `pnpm install` in it once the cause is fixed.

## Run the web app [Client-side] [#run-the-web-app-client-side]

Start every app in the workspace:

```bash
cd my-app
pnpm dev
```

Open the URL Vite prints, such as `http://localhost:5173`. Sign in with a practitioner account of
your project.

### Verify your integration [#verify-your-integration-1]

You should see a list headed **Patients** with up to ten names. If you don't:

1. Check that `OVOK_TENANT_CODE` in `.env` is your project's tenant code.
2. Check that the account is a practitioner of that project.
3. Restart `pnpm dev` after you change `.env`.

## Run the mobile app [Client-side] [#run-the-mobile-app-client-side]

The mobile app is an Expo development build. Build it once for a simulator or a device:

```bash
cd apps/mobile
pnpm ios
```

Run `pnpm android` to build for Android instead. Sign in with a patient account of your project.

## Test your integration [#test-your-integration]

1. Sign in to the web app with a practitioner account.
2. Sign in to the mobile app with a patient account.
3. Try each scenario below.

| Scenario | How to trigger | Expected result |
| --- | --- | --- |
| A practitioner signs in | Sign in to the web app with a practitioner of your project | The **Patients** list shows up to ten patients |
| A wrong password | Sign in to the web app with a wrong password | The form shows the error Ovok returns |
| A second factor | Sign in with an account that has a second factor turned on | The app says the account needs a second factor |
| A patient signs in | Sign in to the mobile app with a patient account | The app shows **Signed in.** |

## Optional: Add an app or a package [Client-side] [#optional-add-an-app-or-a-package-client-side]

```bash
pnpm turbo gen app
pnpm turbo gen package
```

`turbo gen app` asks for the app's name and platform and adds it to `apps/`. `turbo gen package`
adds a shared package to `packages/`.

## Optional: Refresh the Ovok rules [Client-side] [#optional-refresh-the-ovok-rules-client-side]

After you update `create-ovok`, rewrite the Ovok block of every `AGENTS.md`:

```bash
pnpm turbo gen agents
```

It replaces only the text between `BEGIN:ovok-agent-rules` and `END:ovok-agent-rules`. The rest of
each file is yours.

## See also [#see-also]

- [Ovok CLI](/cli)
- [create-ovok reference](/cli/reference/create-ovok)
- [Listen for events](/cli/reference/listen)
- [Set up your project](/authentication/project-setup)
- [Working with AI agents](/working-with-ai-agents)
