# Installation

> Legacy 0.3.1 is supported and retains RPC workers and SQLite memory. Requires Pi 0.99.2 or newer. These docs follow legacy maintenance, not the unchanged v0.3.0 tag. References to master describe the former branch name.

Web page: https://igorwarzocha.github.io/pi-clawa/legacy/docs/getting-started/installation/

Clawa is a Pi package loaded from a git checkout. It is not a standalone agent runtime and it is not
published to npm yet. Keep the package checkout separate from the folder that will become the
Clawa's home.

## What you need

- Git.
- Node.js **24.15 or newer, but lower than 27**.
- [Pi](https://github.com/earendil-works/pi) **0.99.2 or newer**, with a configured model provider.
- A clean folder for the home. [First run](../first-run/) explains the exact bootstrap boundary.

Pi extensions execute with your user permissions. Read the [trust boundaries](../../reference/privacy/)
before putting personal context into a home.

## Install legacy

Legacy **0.3.1**, released on **2026-10-01**, keeps the earlier Clawa architecture on the current
Pi baseline. Choose where package checkouts live, then clone the release tag:

```bash
mkdir -p ~/src
git clone --branch v0.3.1 \
  https://github.com/IgorWarzocha/pi-clawa.git ~/src/pi-clawa
```

This leaves the checkout detached at the release commit. To follow maintenance between releases,
replace `v0.3.1` with `legacy` in the clone command.

Create a separate home:

```bash
mkdir -p ~/clawa-home
cd ~/clawa-home
```

You can try it directly:

```bash
pi -e ~/src/pi-clawa
```

For a permanent project-local install, run the helper **from the home**:

```bash
~/src/pi-clawa/scripts/install-project.sh
pi
```

The helper writes `.pi/settings.json` with the package checkout in `packages`. It refuses to replace
an existing settings file. If the home already has Pi settings, merge this entry yourself instead:

```json
{
  "packages": ["/home/you/src/pi-clawa"]
}
```

Do not use `CLAWA_INSTALL_OVERWRITE=1` casually. It replaces the complete settings file, not only
the package list.

## Branches and releases

Install **v0.3.1** to retain legacy. **Modern v0.4.0** is the default for new homes and has a
different architecture; it is not required to keep legacy working with current Pi. Both releases
require Pi **0.99.2 or newer**. The historical `v0.3.0` tag stays unchanged. The
[release policy](../../project/release-policy/) explains both lines, and the
[edition comparison](https://igorwarzocha.github.io/pi-clawa/versions/) helps you choose between them.

The [files and runtime state](../../reference/files-state/) page separates home data from disposable
runtime artifacts and lists what belongs in a backup or ignore policy.

## Next

Start Pi in the home and continue to [First run](../first-run/). Clawa creates its own files; there is
no separate `init` or setup wizard.