> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started
> Create your first Clara app in minutes.
## What are apps?
Apps let you extend Clara with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
## Prerequisites
Before you begin, make sure the following is installed on your machine:
* **Node.js 24+** — [Download here](https://nodejs.org/)
* **Yarn 4** — Comes with Node.js via Corepack. Enable it by running `corepack enable`
* **Docker** — [Download here](https://www.docker.com/products/docker-desktop/). Required to run a local Clara instance. Not needed if you already have a Clara server running.
## Create your first app
### Scaffold your app
Open a terminal and run:
```bash filename="Terminal" theme={null}
npx create-twenty-app@latest my-twenty-app
```
You will be prompted to enter a name and a description for your app. Press **Enter** to accept the defaults.
This creates a new folder called `my-twenty-app` with everything you need.
### Set up a local Clara instance
The scaffolder will ask:
> **Would you like to set up a local Clara instance?**
* **Type `yes`** (recommended) — This pulls the `twenty-app-dev` Docker image and starts a local Clara server on port `2020`. Make sure Docker is running before you continue.
* **Type `no`** — Choose this if you already have a Clara server running locally.
### Sign in to your workspace
Next, a browser window will open with the Clara login page. Sign in with the pre-seeded demo account:
* **Email:** `tim@apple.dev`
* **Password:** `tim@apple.dev`
### Authorize the app
After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
Click **Authorize** to continue.
Once authorized, your terminal will confirm that everything is set up.
### Start developing
Go into your new app folder and start the development server:
```bash filename="Terminal" theme={null}
cd my-twenty-app
yarn twenty dev
```
This watches your source files, rebuilds on every change, and syncs your app to the local Clara server automatically. You should see a live status panel in your terminal.
For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
```bash filename="Terminal" theme={null}
yarn twenty dev --verbose
```
Dev mode is only available on Clara instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests. Use `yarn twenty deploy` to deploy to production servers — see [Publishing Apps](/developers/extend/apps/publishing) for details.
#### One-shot sync with `yarn twenty dev --once`
If you do not want a watcher running in the background (for example in a CI pipeline, a git hook, or a scripted workflow), pass the `--once` flag. It runs the same pipeline as `yarn twenty dev` — build manifest, bundle files, upload, sync, regenerate the typed API client — but **exits as soon as the sync completes**:
```bash filename="Terminal" theme={null}
yarn twenty dev --once
```
| Command | Behavior | When to use |
| ------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `yarn twenty dev` | Watches your source files and re-syncs on every change. Keeps running until you stop it. | Interactive local development — you want the live status panel and instant feedback loop. |
| `yarn twenty dev --once` | Performs a single build + sync, then exits with code `0` on success or `1` on failure. | Scripts, CI, pre-commit hooks, AI agents, and any non-interactive workflow. |
Both modes require a Clara server running in development mode and an authenticated remote — the same prerequisites apply.
### See your app in Clara
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in your browser. Navigate to **Settings > Apps** and select the **Developer** tab. You should see your app listed under **Your Apps**:
Click on **My twenty app** to open its **application registration**. A registration is a server-level record that describes your app — its name, unique identifier, OAuth credentials, and source (local, npm, or tarball). It lives on the server, not inside any specific workspace. When you install an app into a workspace, Clara creates a workspace-scoped **application** that points back to this registration. One registration can be installed across multiple workspaces on the same server.
Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
You are all set! Edit any file in `src/` and the changes will be picked up automatically.
***
## What you can build
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
| Entity | What it does |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
| **Logic functions** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
| **Front components** | React components that render inside Clara's UI (side panel, widgets, command menu) |
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
| **Page layouts** | Custom record detail pages with tabs and widgets |
Head over to [Building Apps](/developers/extend/apps/building) for a detailed guide on each entity type.
***
## Project structure
The scaffolder generates the following file structure:
```text filename="my-twenty-app/" theme={null}
my-twenty-app/
package.json
yarn.lock
.gitignore
.nvmrc
.yarnrc.yml
.oxlintrc.json
tsconfig.json
tsconfig.spec.json # TypeScript config for tests
vitest.config.ts # Vitest test runner configuration
LLMS.md
README.md
.github/
└── workflows/
└── ci.yml # GitHub Actions CI workflow
public/ # Public assets (images, fonts, etc.)
src/
├── application-config.ts # Required — main application configuration
├── default-role.ts # Default role for logic functions
├── constants/
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
└── __tests__/
├── setup-test.ts # Test setup (server health check, config)
└── app-install.integration-test.ts # Integration test
```
### Starting from an example
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
```bash filename="Terminal" theme={null}
npx create-twenty-app@latest my-twenty-app --example postcard
```
Examples are sourced from the [twenty-apps/examples](https://github.com/getclaratech/clara/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
### Key files
| File / Folder | Purpose |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `package.json` | Declares your app name, version, and dependencies. Includes a `twenty` script so you can run `yarn twenty help` to see all commands. |
| `src/application-config.ts` | **Required.** The main configuration file for your app. |
| `src/default-role.ts` | Default role that controls what your logic functions can access. |
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
| `src/__tests__/` | Integration tests (setup + example test). |
| `public/` | Static assets (images, fonts) served with your app. |
## Local development server
The scaffolder already started a local Clara server for you. To manage it later, use `yarn twenty server`:
| Command | Description |
| -------------------------------------- | ---------------------------------------------- |
| `yarn twenty server start` | Start the local server (pulls image if needed) |
| `yarn twenty server start --port 3030` | Start on a custom port |
| `yarn twenty server start --test` | Start a separate test instance on port 2021 |
| `yarn twenty server stop` | Stop the server (preserves data) |
| `yarn twenty server status` | Show server status, URL, and credentials |
| `yarn twenty server logs` | Stream server logs |
| `yarn twenty server logs --lines 100` | Show the last 100 log lines |
| `yarn twenty server reset` | Delete all data and start fresh |
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
### Running a test instance
Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for running integration tests or experimenting without touching your main dev data.
| Command | Description |
| ---------------------------------- | ----------------------------------------------- |
| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) |
| `yarn twenty server stop --test` | Stop the test instance |
| `yarn twenty server status --test` | Show test instance status, URL, and credentials |
| `yarn twenty server logs --test` | Stream test instance logs |
| `yarn twenty server reset --test` | Wipe test data and start fresh |
The test instance runs in its own Docker container (`twenty-app-dev-test`) with dedicated volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) and config, so it can run in parallel with your main instance without conflicts. Combine `--test` with `--port` to override the default 2021.
The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started.
## Manual setup (without the scaffolder)
If you prefer to set things up yourself instead of using `create-twenty-app`, you can do it in two steps.
**1. Add `twenty-sdk` and `twenty-client-sdk` as dependencies:**
```bash filename="Terminal" theme={null}
yarn add twenty-sdk twenty-client-sdk
```
**2. Add a `twenty` script to your `package.json`:**
```json filename="package.json" theme={null}
{
"scripts": {
"twenty": "twenty"
}
}
```
You can now run `yarn twenty dev`, `yarn twenty help`, and all other commands.
Do not install `twenty-sdk` globally. Always use it as a local project dependency so that each project can pin its own version.
## Troubleshooting
If you run into issues:
* Make sure **Docker is running** before starting the scaffolder with a local instance.
* Make sure you are using **Node.js 24+** (`node -v` to check).
* Make sure **Corepack is enabled** (`corepack enable`) so Yarn 4 is available.
* Try deleting `node_modules` and running `yarn install` again if dependencies seem broken.
Still stuck? Ask for help on the [Clara Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
