---
title: Setup
icon: rocket
description: Clone, install, and run the Reloop monorepo locally.
---
> For the complete documentation index, see [llms-docs.txt](/llms-docs.txt) or the site index [llms.txt](/llms.txt). Full docs corpus: [llms-full-docs.txt](/llms-full-docs.txt). Prefer markdown URLs (append `.md`) for agent consumption. Product skill: [skill.md](/skill.md).


One command from the monorepo root. Full stack at [https://local.reloop.sh](https://local.reloop.sh).


## Prerequisites

| Tool | Notes |
| :--- | :--- |
| [Bun](https://bun.sh/get) | v1.3.0+ |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | Postgres, Redis, Caddy, NATS, Mailpit |
| [mkcert](https://github.com/FiloSottile/mkcert) | Local TLS (`brew install mkcert` on macOS) |
| Git | Clone the repository |


## Quick start

<Tabs>
  <Tab title="One shot">
```bash
git clone git@github.com:reloop-labs/reloop.git
cd reloop
bun setup --start
```
  </Tab>
  <Tab title="Setup, then start">
```bash
git clone git@github.com:reloop-labs/reloop.git
cd reloop
bun setup
bun dev
```
  </Tab>
</Tabs>

`bun setup` only pauses for sudo (hosts / mkcert trust) or a missing tool.


## After setup

<CardGroup cols={2}>
  <Card icon="browser" title="App" href="https://local.reloop.sh">
    Marketing site and entry point
  </Card>
  <Card icon="layout" title="Dashboard" href="https://local.reloop.sh/dashboard">
    Product UI — use this URL, not `localhost:3001`
  </Card>
  <Card icon="book-open" title="Docs" href="https://local.reloop.sh/docs">
    This documentation, served locally
  </Card>
  <Card icon="mail-single" title="Mailpit" href="http://localhost:8025">
    Captured outbound email for local testing
  </Card>
</CardGroup>

<Tip>
Sign up with any email. Local OTP is always `888888`.
</Tip>

<Warning>
Open `https://local.reloop.sh` (not `localhost`) so auth cookies work across services.
</Warning>


## What `bun setup` does

<Steps>
  <Step title="Check Bun and Docker">
    Verifies Bun v1.3+, Docker CLI, and a running daemon. Checks mkcert unless you pass `--skip-tls`.
  </Step>
  <Step title="Map the local domain">
    Adds `127.0.0.1 local.reloop.sh` to `/etc/hosts` (sudo once if needed).
  </Step>
  <Step title="Generate TLS certs">
    Creates trusted PEMs in `local/certs/` with mkcert for Caddy HTTPS.
  </Step>
  <Step title="Install dependencies">
    Runs `bun install` when `node_modules` is missing (or always with `--force`).
  </Step>
  <Step title="Write environment files">
    Copies `.env.dev` → `.env` for backends, `packages/db`, and frontends.
  </Step>
  <Step title="Start Docker and wait for Postgres">
    Brings up core infra, then waits until Postgres is healthy.
  </Step>
  <Step title="Apply the database schema">
    Runs `bun db:push`.
  </Step>
</Steps>


## Flags

| Flag | Effect |
| :--- | :--- |
| `--start` | Run `bun dev` when setup finishes |
| `--force` | Re-run `bun install` even if `node_modules` exists |
| `--skip-docker` | Skip Docker and `db:push` |
| `--skip-hosts` | Skip the `/etc/hosts` entry |
| `--skip-tls` | Skip cert generation (existing PEMs required) |


## Manual setup

Use this only when debugging a specific stage. Run steps in order from the monorepo root.

<Warning>
Skipping or reordering steps can cause database connection errors or broken routing.
</Warning>

<Steps>
  <Step title="Clone and install">
```bash
git clone git@github.com:reloop-labs/reloop.git
cd reloop
bun install
```
  </Step>
  <Step title="Map local domain">
```bash
echo "127.0.0.1 local.reloop.sh" | sudo tee -a /etc/hosts
```

Windows (PowerShell as Administrator):

```powershell
Add-Content -Path $env:windir\System32\drivers\etc\hosts -Value "127.0.0.1`tlocal.reloop.sh"
```
  </Step>
  <Step title="Generate TLS certs">
Caddy serves HTTPS from `local/certs/` (gitignored). Generate once:

```bash
brew install mkcert   # macOS
mkcert -install
mkdir -p local/certs
mkcert -cert-file local/certs/local.reloop.sh.pem \
  -key-file local/certs/local.reloop.sh-key.pem \
  local.reloop.sh "*.local.reloop.sh"
```
  </Step>
  <Step title="Start Docker">
```bash
bun docker:up
```

Free **80**, **443**, **5432**, **6379**, **25**, **465**, and **587** first. See [Port](/docs/setup/port).
  </Step>
  <Step title="Initialize database">
Wait for Postgres, then:

```bash
bun db:push
```
  </Step>
  <Step title="Configure environment">
```bash
bun env:setup
```

Copies `.env.dev` → `.env` for backends, `packages/db`, and `web` / `docs` / `links`. Frontends also ship committed `.env` files with local defaults.

One service manually:

```bash
cp apps/backend/auth/.env.dev apps/backend/auth/.env
```
  </Step>
  <Step title="Start dev servers">
```bash
bun dev
```

Or a subset:

```bash
bun frontend:dev   # frontends only
bun backend:dev    # backends only
```
  </Step>
</Steps>


## Commands

| Command | Description |
| :--- | :--- |
| `bun setup` | One-command local bootstrap |
| `bun setup --start` | Bootstrap, then `bun dev` |
| `bun dev` | All frontend and backend dev servers |
| `bun frontend:dev` | Frontends only |
| `bun backend:dev` | Backends only |
| `bun docker:up` | Start Docker infra (including SMTP/inbound) |
| `bun docker:down` | Stop containers |
| `bun env:setup` | Generate `.env` files |
| `bun db:push` | Apply Drizzle schema |
| `bun db:studio` | Open Drizzle Studio |
| `bun run check` | Lint and format |


## Next

<CardGroup cols={2}>
  <Card icon="globe" title="Port reference" href="/setup/port">
    Local ports and Caddy gateway routes
  </Card>
  <Card icon="shapes" title="Overview" href="/setup/overview">
    Monorepo layout and tech stack
  </Card>
  <Card icon="server" title="Backend services" href="/setup/backend/auth">
    Per-service setup guides
  </Card>
  <Card icon="browser" title="Frontend apps" href="/setup/frontend/web">
    Web, dashboard, docs, links
  </Card>
</CardGroup>