Getting Started - Clara Documentation

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
Yarn 4 — Comes with Node.js via Corepack. Enable it by running corepack enable
Docker — Download here. 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:

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.

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:

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:

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 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:

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 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 for a detailed guide on each entity type.

Project structure

The scaffolder generates the following file structure:

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:

npx create-twenty-app@latest my-twenty-app --example postcard

Examples are sourced from the twenty-apps/examples directory on GitHub. You can also scaffold individual entities into an existing project with yarn twenty add (see Building Apps).

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:

yarn add twenty-sdk twenty-client-sdk

2. Add a twenty script to your package.json:

{
  "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.

​What are apps?

​Prerequisites

​Create your first app

​Scaffold your app

​Set up a local Clara instance

​Sign in to your workspace

​Authorize the app

​Start developing

​One-shot sync with yarn twenty dev --once

​See your app in Clara

​What you can build

​Project structure

​Starting from an example

​Key files

​Local development server

​Running a test instance

​Manual setup (without the scaffolder)

​Troubleshooting

What are apps?

Prerequisites

Create your first app

Scaffold your app

Set up a local Clara instance

Sign in to your workspace

Authorize the app

Start developing

One-shot sync with `yarn twenty dev --once`

See your app in Clara

What you can build

Project structure

Starting from an example

Key files

Local development server

Running a test instance

Manual setup (without the scaffolder)

Troubleshooting