# Installation Guide

Complete guide to setting up Claw for local development.

---

## Prerequisites

| Requirement    | Minimum Version | Notes                                                              |
| -------------- | --------------- | ------------------------------------------------------------------ |
| Node.js        | 22.13.0         | Required by undici 8 + frontier toolchain — LTS 22 or 24 supported |
| npm            | 10.0.0          | Ships with Node 22+                                                |
| Docker         | 24.0.0          | Docker Desktop or Docker Engine                                    |
| Docker Compose | 2.20.0          | Included with Docker Desktop                                       |
| Git            | 2.40.0          | For cloning the repository                                         |

Optional:

- **NVIDIA GPU drivers** and **NVIDIA Container Toolkit** if you want faster local Ollama inference
- **Workspace OAuth credentials** if you want to test GitHub, Slack, Jira, or Google workspace integrations

---

## Quick Start (Automated Installer)

The fastest way to run Claw is with the automated install script. It checks prerequisites, generates secrets, creates your `.env`, and starts all containers:

**Linux / macOS:**

```bash
git clone <repo-url> claw && cd claw
bash scripts/install.sh
```

**Windows (PowerShell):**

```powershell
git clone <repo-url> claw; cd claw
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```

The script will:

- Check that Docker, Node.js 22+, and Git are installed
- Generate secure random secrets (JWT, encryption key, database passwords)
- Prompt for admin email/password (with sensible defaults)
- Create a fully configured `.env` file
- Build and start the full development stack
- Wait for health checks and print access URLs

---

## Quick Start (Manual)

If you prefer to configure manually:

```bash
# 1. Clone the repository
git clone <repo-url> claw
cd claw

# 2. Copy environment file and edit secrets
cp .env.example .env
# Edit .env: set JWT_SECRET, ENCRYPTION_KEY, ADMIN_PASSWORD, and any provider/OAuth credentials

# 3. Start all containers
./scripts/claw.sh up -d

# 4. Verify health
curl http://localhost:4000/api/v1/health
```

### What Starts (35 containers)

| Container                    | Type          | Host Port    | Internal Port |
| ---------------------------- | ------------- | ------------ | ------------- |
| claw-auth-service            | Microservice  | 4001         | 4001          |
| claw-chat-service            | Microservice  | 4002         | 4002          |
| claw-connector-service       | Microservice  | 4003         | 4003          |
| claw-routing-service         | Microservice  | 4004         | 4004          |
| claw-memory-service          | Microservice  | 4005         | 4005          |
| claw-file-service            | Microservice  | 4006         | 4006          |
| claw-audit-service           | Microservice  | 4007         | 4007          |
| claw-ollama-service          | Microservice  | 4008         | 4008          |
| claw-health-service          | Microservice  | 4009         | 4009          |
| claw-client-logs-service     | Microservice  | 4010         | 4010          |
| claw-server-logs-service     | Microservice  | 4011         | 4011          |
| claw-image-service           | Microservice  | 4012         | 4012          |
| claw-file-generation-service | Microservice  | 4013         | 4013          |
| claw-agent-service           | Microservice  | 4015         | 4015          |
| claw-research-service        | Microservice  | 4016         | 4016          |
| claw-workspace-service       | Microservice  | 4017         | 4017          |
| claw-frontend                | Next.js       | 3000         | 3000          |
| claw-nginx                   | Reverse Proxy | 4000         | 80            |
| claw-pg-auth                 | PostgreSQL    | 5441         | 5432          |
| claw-pg-chat                 | PostgreSQL    | 5442         | 5432          |
| claw-pg-connector            | PostgreSQL    | 5443         | 5432          |
| claw-pg-routing              | PostgreSQL    | 5444         | 5432          |
| claw-pg-memory               | PostgreSQL    | 5445         | 5432          |
| claw-pg-files                | PostgreSQL    | 5446         | 5432          |
| claw-pg-ollama               | PostgreSQL    | 5447         | 5432          |
| claw-pg-images               | PostgreSQL    | 5448         | 5432          |
| claw-pg-file-generations     | PostgreSQL    | 5449         | 5432          |
| claw-pg-agent                | PostgreSQL    | 5451         | 5432          |
| claw-pg-research             | PostgreSQL    | 5452         | 5432          |
| claw-pg-workspace            | PostgreSQL    | 5450         | 5432          |
| claw-mongodb                 | MongoDB       | 27018        | 27017         |
| claw-redis                   | Redis         | 6380         | 6379          |
| claw-rabbitmq                | RabbitMQ      | 5672 / 15672 | 5672 / 15672  |
| claw-ollama                  | Ollama        | 11434        | 11434         |
| claw-clamav                  | ClamAV        | 3310         | 3310          |

---

## Step 1: Environment Setup

Copy the example environment file and edit it:

```bash
cp .env.example .env
```

At minimum, update these values:

| Variable         | Action                                              |
| ---------------- | --------------------------------------------------- |
| `JWT_SECRET`     | Generate a random 64-character string               |
| `ENCRYPTION_KEY` | Generate a random 32-byte hex string (64 hex chars) |
| `ADMIN_PASSWORD` | Set the initial admin password                      |

If you want to test the newer platform capabilities, also review:

| Variable                                    | Purpose                              |
| ------------------------------------------- | ------------------------------------ |
| `WORKSPACE_SERVICE_URL`                     | Internal workspace service base URL  |
| `AGENT_SERVICE_URL`                         | Internal agent service base URL      |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub workspace OAuth               |
| `SLACK_CLIENT_ID` / `SLACK_CLIENT_SECRET`   | Slack workspace OAuth                |
| `JIRA_CLIENT_ID` / `JIRA_CLIENT_SECRET`     | Jira workspace OAuth                 |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Google workspace OAuth               |
| `CLAMAV_ENABLED`                            | Enable or disable antivirus scanning |

To generate secure random values:

```bash
# JWT_SECRET (64 characters)
openssl rand -base64 48

# ENCRYPTION_KEY (32 bytes as hex)
openssl rand -hex 32
```

---

## Step 2: Start All Services

```bash
./scripts/claw.sh up -d
```

Wait for all containers to become healthy (this may take 30-60 seconds on first run, longer if Ollama pulls models or ClamAV refreshes signatures):

```bash
./scripts/claw.sh ps
```

All 35 containers should show status `running` or `healthy`.

---

## Step 3: Verify Health

The health service aggregates status from the platform services:

```bash
curl http://localhost:4000/api/v1/health
```

You should receive a JSON response showing each service's health status.

---

## Step 4: First Login

### Via the Frontend

1. Open `http://localhost:3000` in your browser.
2. Log in with your admin credentials:
   - **Email**: `admin@claw.local` (or your configured `ADMIN_EMAIL`)
   - **Password**: the value you set for `ADMIN_PASSWORD` in `.env`
3. You should see the Claw dashboard.

### Via the API (through Nginx)

```bash
curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@claw.local", "password": "your-admin-password"}'
```

### Via the Auth Service Directly

```bash
curl -X POST http://localhost:4001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@claw.local", "password": "your-admin-password"}'
```

---

## Access Points

| What                | URL                    |
| ------------------- | ---------------------- |
| Frontend            | http://localhost:3000  |
| API (via Nginx)     | http://localhost:4000  |
| Auth Service        | http://localhost:4001  |
| Chat Service        | http://localhost:4002  |
| Connector Service   | http://localhost:4003  |
| Routing Service     | http://localhost:4004  |
| Memory Service      | http://localhost:4005  |
| File Service        | http://localhost:4006  |
| Audit Service       | http://localhost:4007  |
| Ollama Service      | http://localhost:4008  |
| Health Service      | http://localhost:4009  |
| Client Logs Service | http://localhost:4010  |
| Server Logs Service | http://localhost:4011  |
| Image Service       | http://localhost:4012  |
| File Generation     | http://localhost:4013  |
| Agent Service       | http://localhost:4015  |
| Research Service    | http://localhost:4016  |
| Workspace Service   | http://localhost:4017  |
| RabbitMQ Management | http://localhost:15672 |
| Ollama Runtime      | http://localhost:11434 |

Default RabbitMQ management credentials come from `RABBITMQ_USER` / `RABBITMQ_PASSWORD` in `.env`.

After first login, use the routing replay and intelligence views to confirm the router is learning from telemetry and replay data:

- Replay Lab: `http://localhost:3000/routing/replay`
- Routing insights: `/api/v1/routing/adaptive-insights`

---

## Running Individual Services Locally (Outside Docker)

For active development on a specific service, you can run it outside Docker while keeping infrastructure containers running.

### 1. Start Infrastructure Only

Start only the databases, Redis, RabbitMQ, Ollama, ClamAV, and Nginx:

```bash
./scripts/claw.sh up -d \
  pg-auth pg-chat pg-connector pg-routing pg-memory pg-files pg-ollama \
  pg-images pg-file-generations pg-agent pg-research pg-workspace \
  mongodb redis rabbitmq ollama clamav nginx
```

### 2. Install Dependencies

```bash
npm install
```

This installs dependencies for all workspaces:

- Root workspace (shared tooling)
- All 17 service apps
- `apps/claw-frontend` (Next.js)
- All 5 shared packages

### 3. Build Shared Packages

Shared packages must be built before services can import them:

```bash
npm run build -w packages/shared-types
npm run build -w packages/shared-constants
npm run build -w packages/shared-rabbitmq
npm run build -w packages/shared-auth
```

### 4. Run a Single Service

```bash
# Example: run the auth service locally
npm run dev --workspace=claw-auth-service

# Example: run the workspace service locally
npm run dev --workspace=claw-workspace-service

# Example: run the agent service locally
npm run dev --workspace=claw-agent-service

# Example: run the frontend locally
npm run dev:frontend
```

Each service reads the root `.env` file for service URLs and database connection strings. When running locally, ensure the connection strings point to `localhost` with the correct host ports (for example `localhost:5450` for the workspace database).

---

## GPU / Ollama Setup

### Running Ollama in Docker

The development stack includes the Ollama runtime by default:

```bash
./scripts/claw.sh up -d ollama ollama-service
```

This starts the Ollama container on port `11434`.

### Running Ollama With GPU

Prerequisites:

1. For NVIDIA GPUs, install [NVIDIA GPU drivers](https://www.nvidia.com/drivers) for your card.
2. For NVIDIA GPUs in Docker, install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html).
3. Verify GPU access on your platform:
   - NVIDIA: `nvidia-smi` should show your GPU.
   - macOS / Apple Silicon: use native Ollama on the host if you want Metal acceleration.
   - AMD / Radeon: the installer will detect the GPU, but Docker passthrough still depends on your runtime setup.

The current dev stack does not use a separate Docker profile for GPU. If Docker can see the GPU on a supported host, Ollama can use it automatically.

### Pulling Local Models

Once Ollama is running, pull the models you want to use:

```bash
# Recommended router / local reasoning models
docker exec claw-ollama ollama pull gemma3:4b
docker exec claw-ollama ollama pull qwen3:1.7b

# General-purpose local models
docker exec claw-ollama ollama pull llama3.1:8b
docker exec claw-ollama ollama pull mistral:7b

# Verify available models
docker exec claw-ollama ollama list
```

### Ollama on Host (Without Docker)

If you prefer running Ollama directly on your host:

1. Install Ollama from [ollama.com](https://ollama.com).
2. Start it: `ollama serve`.
3. Set `OLLAMA_BASE_URL=http://host.docker.internal:11434` in your `.env` so Docker services can reach it.
4. Pull models: `ollama pull gemma3:4b`.

---

## Workspace and Agent Setup

### Workspace Service

To test workspace integrations:

1. Add the provider credentials you need to `.env`
2. Start the stack
3. Open the workspace UI flows through the frontend or call `/api/v1/workspace/*`

Core workspace routes:

- `/api/v1/workspace/connectors`
- `/api/v1/workspace/oauth/init`
- `/api/v1/workspace/search`
- `/api/v1/workspace/actions`

### Agent Service

The agent backend runs at `http://localhost:4015` and the local CLI lives in `agent-cli/`.

Typical flow:

1. Start the backend stack
2. Sign in through the frontend
3. Register the CLI against the agent service
4. Approve or reject commands from the UI
5. Review repos and file events through `/api/v1/agent/*`

---

## Port Mapping Reference

| Host Port | Container Port | Service                       |
| --------- | -------------- | ----------------------------- |
| 4000      | 80             | Nginx reverse proxy           |
| 3000      | 3000           | Frontend (Next.js)            |
| 4001      | 4001           | Auth service                  |
| 4002      | 4002           | Chat service                  |
| 4003      | 4003           | Connector service             |
| 4004      | 4004           | Routing service               |
| 4005      | 4005           | Memory service                |
| 4006      | 4006           | File service                  |
| 4007      | 4007           | Audit service                 |
| 4008      | 4008           | Ollama service                |
| 4009      | 4009           | Health service                |
| 4010      | 4010           | Client logs service           |
| 4011      | 4011           | Server logs service           |
| 4012      | 4012           | Image service                 |
| 4013      | 4013           | File generation service       |
| 4015      | 4015           | Agent service                 |
| 4016      | 4016           | Research service              |
| 4017      | 4017           | Workspace service             |
| 5441      | 5432           | PostgreSQL (auth)             |
| 5442      | 5432           | PostgreSQL (chat)             |
| 5443      | 5432           | PostgreSQL (connector)        |
| 5444      | 5432           | PostgreSQL (routing)          |
| 5445      | 5432           | PostgreSQL (memory)           |
| 5446      | 5432           | PostgreSQL (files)            |
| 5447      | 5432           | PostgreSQL (ollama)           |
| 5448      | 5432           | PostgreSQL (images)           |
| 5449      | 5432           | PostgreSQL (file generations) |
| 5451      | 5432           | PostgreSQL (agent)            |
| 5452      | 5432           | PostgreSQL (research)         |
| 5450      | 5432           | PostgreSQL (workspace)        |
| 27018     | 27017          | MongoDB                       |
| 6380      | 6379           | Redis                         |
| 5672      | 5672           | RabbitMQ (AMQP)               |
| 15672     | 15672          | RabbitMQ (Management UI)      |
| 11434     | 11434          | Ollama runtime                |
| 3310      | 3310           | ClamAV                        |

---

## Troubleshooting

### Port Conflicts

If any ports are already in use, update the corresponding port mappings in the split compose files (`docker/docker-compose.dev.databases.yml` for databases, `docker/docker-compose.dev.services.yml` for services) and the relevant `.env` variables.

### Container Fails to Start

Check the logs for the specific container:

```bash
./scripts/claw.sh logs claw-auth-service
./scripts/claw.sh logs claw-pg-auth
```

### Database Connection Issues

Ensure the relevant PostgreSQL container is running and healthy:

```bash
./scripts/claw.sh ps
```

### RabbitMQ Connection Refused

RabbitMQ can take 15-30 seconds to fully start. Check its status:

```bash
./scripts/claw.sh logs claw-rabbitmq
```

Services will retry RabbitMQ connections automatically.

### Workspace OAuth Callback Fails

Verify that the provider client ID, secret, and redirect URL in `.env` match the provider application configuration.

### Agent Session Never Connects

Check that:

- the agent service is healthy
- the CLI is pointed at the correct base URL
- the JWT used during registration is still valid

### Permission Errors on Linux

If Docker commands require `sudo`, add your user to the `docker` group:

```bash
sudo usermod -aG docker $USER
# Log out and back in for the change to take effect
```

### Clean Restart

To reset everything and start fresh:

```bash
./scripts/claw.sh down -v
npm run clean
npm install
./scripts/claw.sh up -d
```
