Managing the local server
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 2.2.0 | Start a specific server version |
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 |
twenty-app-dev-data for PostgreSQL, twenty-app-dev-storage for files). Use reset to wipe everything.
Pinning the server version
When no version is passed, docker:start resolves the version from your app’s engines.twenty range in package.json — the same range the server validates against when your app is installed. It starts the newest published twenty-app-dev image that satisfies the range, falling back to latest when the field is absent or no published version matches:
{
"engines": {
"twenty": ">=2.2.0"
}
}
yarn twenty docker:start 2.3.0. If a container already exists on a different version, docker:start upgrades it in place (recreating the container while preserving your data volumes).
Upgrading the server image
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
yarn twenty docker:status (it shows the APP_VERSION baked into the container).
Running a parallel test instance
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 |
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:
yarn add twenty-sdk twenty-client-sdk
package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty docker:start, and the rest.
Don’t install twenty-sdk globally — pin it per project so each app uses its own version.
