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

# Development Setup

> Set up a local Memorose development environment against the current repo layout and scripts.

# Development Setup

## Prerequisites

| Tool              | Version | Notes                                        |
| ----------------- | ------- | -------------------------------------------- |
| Rust              | 1.88+   | Pinned via `rust-toolchain` in the repo root |
| Node.js           | 20+     | For the dashboard frontend                   |
| pnpm              | latest  | Dashboard package manager                    |
| protobuf-compiler | —       | Required by Raft transport build steps       |
| cmake             | —       | Required by some native dependencies         |
| libclang-dev      | —       | Required by `bindgen` on Linux               |

### macOS

```bash theme={null}
brew install protobuf cmake node
npm i -g pnpm
rustup install 1.88.0
```

### Ubuntu / Debian

```bash theme={null}
sudo apt install -y protobuf-compiler cmake libclang-dev
npm i -g pnpm
rustup install 1.88.0
```

## Clone and build

```bash theme={null}
git clone https://github.com/ai-akashic/Memorose.git
cd Memorose
cargo build
```

The workspace contains four crates: `memorose-common`, `memorose-core`, `memorose-server`, and `memorose-gateway`.

For the dashboard frontend:

```bash theme={null}
cd dashboard
pnpm install
pnpm build
```

## Configuration

Copy the example environment file:

```bash theme={null}
cp .env.example .env
```

At minimum, set one provider key and model names:

```bash theme={null}
GOOGLE_API_KEY=your_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004
```

If you want to force the provider via env, prefer:

```bash theme={null}
MEMOROSE__LLM__PROVIDER=Gemini
```

Or:

```bash theme={null}
MEMOROSE__LLM__PROVIDER=OpenAI
OPENAI_API_KEY=your_key_here
```

Create `config.toml` manually using the current schema in `crates/memorose-common/src/config.rs`. Do not rely on `config.example.toml` as a fully current template.

## Running locally

### Standalone mode

The fastest way to get one local node running:

```bash theme={null}
./scripts/start_cluster.sh start --mode standalone
```

This starts one API node on port `3000` and the dashboard on `3100`.

### Local cluster mode

To simulate a 3-node local Raft cluster:

```bash theme={null}
./scripts/start_cluster.sh start --clean --build
```

### Other helper commands

```bash theme={null}
./scripts/start_cluster.sh status
./scripts/start_cluster.sh stop
./scripts/start_cluster.sh restart --clean
```

### Dashboard dev server

For frontend development with hot reload:

```bash theme={null}
cd dashboard
pnpm dev
```

## Ports

| Service      | Port      | Notes                      |
| ------------ | --------- | -------------------------- |
| API (node 1) | 3000      | Primary local node         |
| API (node 2) | 3001      | Local cluster mode only    |
| API (node 3) | 3002      | Local cluster mode only    |
| Gateway      | 8080      | `docker-compose.yml` only  |
| Dashboard    | 3100      | Next.js frontend           |
| Raft         | 5001–5003 | Internal consensus traffic |

## Docker

A `docker-compose.yml` is provided:

```bash theme={null}
docker compose up
```

This starts the gateway, two server nodes, and the dashboard.

<Note>
  When running the dashboard in Docker, set `DASHBOARD_API_ORIGIN` to the backend container URL, for example `http://memorose-node-0:3000`. Otherwise the dashboard will try to call `127.0.0.1:3000` inside its own container and fail.
</Note>