> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Setup

> 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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}

    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 theme={null}
    git clone git@github.com:twentyhq/twenty.git
    ```
  </Tab>

  <Tab title="HTTPS">
    ```bash theme={null}
    git clone https://github.com/twentyhq/twenty.git
    ```
  </Tab>
</Tabs>

## Step 2: Position yourself at the root

```bash theme={null}
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 theme={null}
      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 theme={null}
      make -C packages/twenty-docker postgres-on-docker
    ```
  </Tab>

  <Tab title="Mac OS">
    **Option 1 (preferred):** To provision your database locally with `brew`:

    ```bash theme={null}
      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 theme={null}
      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 theme={null}
      # Connect to PostgreSQL
      psql postgres
      or
      psql -U $(whoami) -d postgres
    ```

    Once at the psql prompt (postgres=#), run:

    ```bash theme={null}
     # List existing PostgreSQL roles
     \du
    ```

    You'll see output similar to:

    ```bash theme={null}
     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 theme={null}
     CREATE ROLE postgres WITH SUPERUSER LOGIN;
    ```

    This creates a superuser role named `postgres` with login access.

    ```bash theme={null}
    Role name | Attributes  | Member of
    -----------+-------------+-----------
    postgres  | Superuser   | {}
    john      | Superuser   | {}
    ```

    **Option 2:** If you have docker installed:

    ```bash theme={null}
      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 theme={null}
      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 theme={null}
      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 theme={null}
      make -C packages/twenty-docker redis-on-docker
    ```
  </Tab>

  <Tab title="Mac OS">
    **Option 1 (preferred):** To provision your Redis locally with `brew`:

    ```bash theme={null}
    brew install redis
    ```

    Start your Redis server:

    ```bash theme={null}
    brew services start redis
    ```

    **Option 2:** If you have docker installed:

    ```bash theme={null}
      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 theme={null}
      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 theme={null}
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 theme={null}
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 theme={null}
    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 theme={null}
npx nx database:reset twenty-server
```

Start the server, the worker and the frontend services:

```bash theme={null}
npx nx start twenty-server
npx nx worker twenty-server
npx nx start twenty-front
```

Alternatively, you can start all services at once:

```bash theme={null}
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.