--- title: Getting Started icon: "rocket" description: Create your first Twenty app in minutes. --- ## Prerequisites - **Node.js 24+** — [Download](https://nodejs.org/) - **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable` - **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere. Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix. | Phase | What you do | Tool | Result | |---|---|---|---| | **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk | | **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty server` | A running Twenty instance | | **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI | --- ## Phase 1 — Scaffold your project Create a new app from the template: ```bash filename="Terminal" npx create-twenty-app@latest my-twenty-app ``` You'll be prompted for a name and description — press **Enter** for the defaults. This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, a CI workflow, and an integration test. **After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2. --- ## Phase 2 — Run a local Twenty server Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI. The scaffolder offers to start one for you: > **Would you like to set up a local Twenty instance?** - **Yes (recommended)** — pulls the `twentycrm/twenty-app-dev` Docker image and starts it on port `2020`. Make sure Docker is running first. - **No** — choose this if you already have a Twenty server you want to connect to. You can wire it up later with `yarn twenty remote add`.
Should start local instance?
Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account: - **Email:** `tim@apple.dev` - **Password:** `tim@apple.dev`
Twenty login screen
Click **Authorize** on the next screen — this gives the CLI access to your workspace.
Twenty CLI authorization screen
Your terminal will confirm everything is set up.
App scaffolded successfully
**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it. If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty server start` — no need to re-scaffold. --- ## Phase 3 — Sync your changes This is the inner loop you'll spend most of your time in. ```bash filename="Terminal" cd my-twenty-app yarn twenty dev ``` This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a second the server reflects the change. You'll see a live status panel in your terminal. For more detailed output (build logs, sync requests, error traces), add `--verbose`.
Dev mode terminal output
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
Your Apps list showing My twenty app
Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
Application registration details
Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
Installed app
**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI. ### One-shot sync for CI and scripts Pass `--once` to run a single build + sync and exit — same pipeline, no watcher: ```bash filename="Terminal" yarn twenty dev --once ``` | Command | Behavior | When to use | |---------|----------|-------------| | `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. | | `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. | Both modes need a server in development mode and an authenticated remote. 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](/developers/extend/apps/publishing). --- ## 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** | Custom data models (Post Card, Invoice, etc.) with typed fields | | **Logic functions** | Server-side TypeScript 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 | | **Page layouts** | Custom record detail pages with tabs and widgets | Full reference: [Building Apps](/developers/extend/apps/building). ## Project structure ```text filename="my-twenty-app/" my-twenty-app/ package.json src/ application-config.ts # Required — your app's entry point default-role.ts # Permissions for logic functions constants/ universal-identifiers.ts # Auto-generated UUIDs and metadata __tests__/ setup-test.ts app-install.integration-test.ts .github/workflows/ci.yml # GitHub Actions public/ # Static assets vitest.config.ts # Test runner config tsconfig.json, tsconfig.spec.json .nvmrc, .yarnrc.yml, .oxlintrc.json README.md, LLMS.md ``` | File / Folder | Purpose | |---|---| | `src/application-config.ts` | **Required.** The main configuration file for your app. | | `src/default-role.ts` | Default role controlling what your logic functions can access. | | `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). | | `src/__tests__/` | Integration tests (setup + example test). | | `public/` | Static assets (images, fonts) served with your app. | ### Starting from an example Use `--example` to start with a more complete project (custom objects, fields, logic functions, front components): ```bash filename="Terminal" npx create-twenty-app@latest my-twenty-app --example postcard ``` Examples live in [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). 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). --- ## Managing the local server Use `yarn twenty server` to control the local Twenty container: | Command | What it does | |---------|--------------| | `yarn twenty server start` | Start the server (pulls the 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 URL, version, and login credentials | | `yarn twenty server logs` | Stream server logs | | `yarn twenty server reset` | Wipe data and start fresh | | `yarn twenty server upgrade` | Pull the latest `twenty-app-dev` image | | `yarn twenty server upgrade 2.2.0` | Upgrade to a specific version | Data persists across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything. ### Upgrading the server image `yarn twenty server upgrade` pulls the latest image, compares digests, and only recreates the container if anything actually changed. Volumes are preserved — only the container is replaced. If a new image was pulled and the container was running, the upgrade automatically starts a new container; run `yarn twenty server start` afterward to wait for it to become healthy. ```bash filename="Terminal" yarn twenty server upgrade # Latest yarn twenty server upgrade 2.2.0 # Specific version ``` Verify the running version with `yarn twenty server status` (it shows the `APP_VERSION` baked into the container). ### Running a parallel test instance Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for integration tests or experiments without touching your main dev data: | Command | What it does | |---------|--------------| | `yarn twenty server start --test` | Start the test instance (defaults to port 2021) | | `yarn twenty server stop --test` | Stop it | | `yarn twenty server status --test` | Show its status | | `yarn twenty server logs --test` | Stream its logs | | `yarn twenty server reset --test` | Wipe its data | | `yarn twenty server upgrade --test` | Upgrade its image | The test instance has its own container (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), and config — it runs alongside your main instance without conflicts. Combine `--test` with `--port` to override 2021. --- ## Manual setup (without the scaffolder) Skip the scaffolder if you're adding the SDK to an existing project: ```bash filename="Terminal" yarn add twenty-sdk twenty-client-sdk ``` Add the script to `package.json`: ```json filename="package.json" { "scripts": { "twenty": "twenty" } } ``` You can now run `yarn twenty dev`, `yarn twenty server start`, and the rest. Don't install `twenty-sdk` globally — pin it per project so each app uses its own version. --- ## Troubleshooting - **Docker errors** — Make sure Docker Desktop (or the daemon) is running before `yarn twenty server start`. The error message will show the right start command for your OS. - **Wrong Node version** — Need 24+. Check with `node -v`. - **Yarn 4 missing** — Run `corepack enable`. - **Dependencies broken** — `rm -rf node_modules && yarn install`. Stuck? Ask on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).