upstream-twenty/packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx

---
title: Local Setup
icon: "laptop-code"
description: "The guide for contributors (or curious developers) who want to run Twenty locally."
---


## Prerequisites

<Tabs>
<Tab title="Linux and macOS">

Before you can install and use Twenty, make sure you install the following on your computer:
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Node v24.5.0](https://nodejs.org/en/download)
- [yarn v4](https://yarnpkg.com/getting-started/install)
- [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)

<Warning>
`npm` won't work, you should use `yarn` instead. Yarn is now shipped with Node.js, so you don't need to install it separately.
You only have to run `corepack enable` to enable Yarn if you haven't done it yet.
</Warning>

</Tab>

<Tab title="Windows (WSL)">

1. Install WSL
Open PowerShell as Administrator and run:
```powershell
wsl --install
```
You should now see a prompt to restart your computer. If not, restart it manually.

Upon restart, a PowerShell window will open and install Ubuntu. This may take up some time.
You'll see a prompt to create a username and password for your Ubuntu installation.

2. Install and configure git

```bash
sudo apt-get install git

git config --global user.name "Your Name"

git config --global user.email "youremail@domain.com"
```

3. Install nvm, node.js and yarn

<Warning>
Use `nvm` to install the correct `node` version. The `.nvmrc` ensures all contributors use the same version.
</Warning>

```bash
sudo apt-get install curl

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```
Close and reopen your terminal to use nvm. Then run the following commands.

```bash

nvm install # installs recommended node version

nvm use # use recommended node version

corepack enable
```

</Tab>
</Tabs>

---

## Step 1: Git Clone

In your terminal, run the following command.

<Tabs>
<Tab title="SSH (Recommended)">
If you haven't already set up SSH keys, you can learn how to do so [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
```bash
git clone git@github.com:twentyhq/twenty.git
```
</Tab>
<Tab title="HTTPS">

```bash
git clone https://github.com/twentyhq/twenty.git
```

</Tab>
</Tabs>

## Step 2: Position yourself at the root

```bash
cd twenty
```

You should run all commands in the following steps from the root of the project.

## Step 3: Set up a PostgreSQL Database

<Tabs>
  <Tab title="Linux">
    **Option 1 (preferred):** To provision your database locally:
    Use the following link to install PostgreSQL on your Linux machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
    Note: You might need to add `sudo -u postgres` to the command before `psql` to avoid permission errors.

    **Option 2:** If you have docker installed:
    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>
  <Tab title="Mac OS">
    **Option 1 (preferred):** To provision your database locally with `brew`:

    ```bash
      brew install postgresql@16
      export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
      brew services start postgresql@16
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```

    You can verify if the PostgreSQL server is running by executing:
    ```bash
      brew services list
    ```

    The installer might not create the `postgres` user by default when installing
    via Homebrew on macOS. Instead, it creates a PostgreSQL role that matches your macOS
    username (e.g., "john").
    To check and create the `postgres` user if necessary, follow these steps:
    ```bash
      # Connect to PostgreSQL
      psql postgres
      or
      psql -U $(whoami) -d postgres
    ```

    Once at the psql prompt (postgres=#), run:
     ```bash
      # List existing PostgreSQL roles
      \du
    ```
    You'll see output similar to:
     ```bash
      Role name | Attributes  | Member of
      -----------+-------------+-----------
      john      | Superuser   | {}
    ```

    If you do not see a `postgres` role listed, proceed to the next step.
    Create the `postgres` role manually:
     ```bash
      CREATE ROLE postgres WITH SUPERUSER LOGIN;
    ```
    This creates a superuser role named `postgres` with login access.
      ```bash
      Role name | Attributes  | Member of
      -----------+-------------+-----------
      postgres  | Superuser   | {}
      john      | Superuser   | {}
    ```

    **Option 2:** If you have docker installed:
    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>
  <Tab title="Windows (WSL)">
    All the following steps are to be run in the WSL terminal (within your virtual machine)

    **Option 1:** To provision your PostgreSQL locally:
    Use the following link to install PostgreSQL on your Linux virtual machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
    Note: You might need to add `sudo -u postgres` to the command before `psql` to avoid permission errors.

    **Option 2:** If you have docker installed:
    Running Docker on WSL adds an extra layer of complexity.
    Only use this option if you are comfortable with the extra steps involved, including turning on [Docker Desktop WSL2](https://docs.docker.com/desktop/wsl).
    ```bash
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>
</Tabs>

You can now access the database at `localhost:5432`.

If you used the Docker option above, the default credentials are user `postgres` and password `postgres`. For native PostgreSQL installations, use the credentials and roles configured on your machine.

## Step 4: Set up a Redis Database (cache)
Twenty requires a Redis cache to provide the best performance.

<Tabs>
  <Tab title="Linux">
    **Option 1:** To provision your Redis locally:
    Use the following link to install Redis on your Linux machine: [Redis Installation](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)

    **Option 2:** If you have docker installed:
    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>
  <Tab title="Mac OS">
    **Option 1 (preferred):** To provision your Redis locally with `brew`:
    ```bash
    brew install redis
    ```
    Start your Redis server:
    ```bash
    brew services start redis
    ```

    **Option 2:** If you have docker installed:
    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>
  <Tab title="Windows (WSL)">
    **Option 1:** To provision your Redis locally:
    Use the following link to install Redis on your Linux virtual machine: [Redis Installation](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)

    **Option 2:** If you have docker installed:
    ```bash
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>
</Tabs>

If you need a client GUI, we recommend [Redis Insight](https://redis.io/insight/) (free version available).

## Step 5: Set up environment variables

Use environment variables or `.env` files to configure your project. More info [here](/developers/self-host/capabilities/setup).

Copy the `.env.example` files in `/front` and `/server`:
```bash
cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env
```

<Info>
**Multi-Workspace Mode:** By default, Twenty runs in single-workspace mode where only one workspace can be created. To enable multi-workspace support (useful for testing subdomain-based features), set `IS_MULTIWORKSPACE_ENABLED=true` in your server `.env` file. See [Multi-Workspace Mode](/developers/self-host/capabilities/setup#multi-workspace-mode) for details.
</Info>

## Step 6: Installing dependencies
To build Twenty server and seed some data into your database, run the following command:
```bash
yarn
```
Note that `npm` or `pnpm` won't work

## Step 7: Running the project

<Tabs>
  <Tab title="Linux">
    Depending on your Linux distribution, Redis server might be started automatically.
    If not, check the [Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) for your distro.
  </Tab>
  <Tab title="Mac OS">
  Redis should already be running. If not, run:
    ```bash
    brew services start redis
    ```
  </Tab>
  <Tab title="Windows (WSL)">
    Depending on your Linux distribution, Redis server might be started automatically.
    If not, check the [Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) for your distro.
  </Tab>
</Tabs>


Set up your database with the following command:
```bash
npx nx database:reset twenty-server
```

Start the server, the worker and the frontend services:
```bash
npx nx start twenty-server
npx nx worker twenty-server
npx nx start twenty-front
```

Alternatively, you can start all services at once:
```bash
npx nx start
```

## Step 8: Use Twenty

**Frontend**

Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001).
You can log in using the default demo account: `tim@apple.dev` (password: `tim@apple.dev`)

**Backend**

- Twenty's server will be up and running at [http://localhost:3000](http://localhost:3000)
- The GraphQL API can be accessed at [http://localhost:3000/graphql](http://localhost:3000/graphql)
- The REST API can be reached at [http://localhost:3000/rest](http://localhost:3000/rest)



## Troubleshooting

If you encounter any problem, check [Troubleshooting](/developers/self-host/capabilities/troubleshooting) for solutions.