Local Server

Manage the local Twenty Docker server — start, stop, upgrade, parallel test instance, and manual SDK setup.

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

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.

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"
  }
}

Pass a version explicitly to override the range for a single run: 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

Verify the running version with 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

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:

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.

Don’t install twenty-sdk globally — pin it per project so each app uses its own version.