packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx
Use yarn twenty docker:* to control the local Twenty container:
| Command | What it does |
|---|---|
yarn twenty docker:start | Start the server (pulls the image if needed) |
yarn twenty docker:start --port 3030 | Start on a custom port |
yarn twenty docker:stop | Stop the server (preserves data) |
yarn twenty docker:status | Show URL, version, and login credentials |
yarn twenty docker:logs | Stream server logs |
yarn twenty docker:reset | Wipe data and start fresh |
yarn twenty docker:upgrade | Pull the latest twenty-app-dev image |
yarn twenty docker: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.
yarn twenty docker: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 docker:start afterward to wait for it to become healthy.
yarn twenty docker:upgrade # Latest
yarn twenty docker:upgrade 2.2.0 # Specific version
Verify the running version with yarn twenty docker:status (it shows the APP_VERSION baked into the container).
Pass --test to any docker:* 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 docker:start --test | Start the test instance (defaults to port 2021) |
yarn twenty docker:stop --test | Stop it |
yarn twenty docker:status --test | Show its status |
yarn twenty docker:logs --test | Stream its logs |
yarn twenty docker:reset --test | Wipe its data |
yarn twenty docker: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.
Skip the scaffolder if you're adding the SDK to an existing project:
yarn add twenty-sdk twenty-client-sdk
Add the script to package.json:
{
"scripts": {
"twenty": "twenty"
}
}
You can now run yarn twenty dev, yarn twenty docker:start, and the rest.