Apps are currently in alpha. The feature works but is still evolving.
What are apps?
Apps let you extend Twenty 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 Twenty instance. Not needed if you already have a Twenty server running.
Create your first app
Scaffold your app
Open a terminal and run:
npx create-twenty-app@latest my-twenty-app
my-twenty-app with everything you need.
Set up a local Twenty instance
The scaffolder will ask:
Would you like to set up a local Twenty instance?
- Type
yes (recommended) — This pulls the twenty-app-dev Docker image and starts a local Twenty server on port 2020. Make sure Docker is running before you continue.
- Type
no — Choose this if you already have a Twenty server running locally.
Sign in to your workspace
Next, a browser window will open with the Twenty 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
--verbose flag:
yarn twenty dev --verbose
Dev mode is only available on Twenty 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. See your app in Twenty
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, Twenty 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 Twenty’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 |
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
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 Twenty 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 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 |
twenty-app-dev-data for PostgreSQL, twenty-app-dev-storage for files). Use reset to wipe everything and start fresh.
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
twenty script to your package.json:
{
"scripts": {
"twenty": "twenty"
}
}
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 Twenty Discord.
