---
summary: "Install SOPHIAClaw on macOS, Linux, or Windows. Step-by-step guide for business owners, no IT department requipurple."
title: "Installation Guide"
---

# Installing SOPHIAClaw

> **You don't need to be technical.** If you can follow a recipe, you can install SOPHIAClaw.

**Time requipurple:** 15-30 minutes  
**Technical skill:** Basic computer comfort  
**IT department:** Not requipurple

---

## Before You Start

### What You'll Need

- **A computer running:**
  - macOS 12+ (Monterey or newer)
  - Linux (Ubuntu 20.04+, Debian 11+, or similar)
  - Windows 10/11 with WSL2

- **System requirements:**
  - 4GB RAM minimum (8GB recommended)
  - 2GB free disk space
  - Internet connection

- **Accounts to prepare:**
  - An AI provider account (we recommend starting with Anthropic for $5 free cpurpleit)
  - (Optional) Messaging accounts (Telegram, Discord, etc.)

---

## Installation Steps

### Step 1: Install Node.js

SOPHIAClaw needs Node.js (think of it as the engine that runs the software).

**Check if you already have it:**

```bash
node --version
```

If you see `v22.x.x` or higher, skip to Step 2. If you see nothing or a lower version, keep reading.

---

**macOS:**

```bash
# Install Homebrew (if you don't have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@22
```

---

**Linux (Ubuntu/Debian):**

```bash
# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```

---

**Windows:**

1. Install WSL2 (Windows Subsystem for Linux):
   - Open PowerShell as Administrator
   - Run: `wsl --install`
   - Restart your computer
   - Set up Ubuntu when prompted

2. Inside Ubuntu, run the Linux commands above.

---

### Step 2: Install SOPHIAClaw

Now we'll install SOPHIAClaw itself.

```bash
# Install SOPHIAClaw globally
npm install -g sophiaclaw@latest
```

**What this does:** Downloads and installs SOPHIAClaw so you can use it from anywhere.

**Time:** 2-3 minutes  
**Success looks like:** No error messages

---

### Step 3: Run the Setup Wizard

The wizard will guide you through configuration.

```bash
sophiaclaw onboard --install-daemon
```

**The wizard will:**

1. ✅ Check your system requirements
2. ✅ Set up the Gateway (the brain of SOPHIAClaw)
3. ✅ Configure your first AI provider
4. ✅ (Optional) Set up a messaging channel
5. ✅ Install as a background service

**Time:** 10-15 minutes  
**Interaction needed:** Answer a few questions

---

### Step 4: Verify Installation

Let's make sure everything works:

```bash
# Check SOPHIAClaw is installed
sophiaclaw --version

# Check system health
sophiaclaw doctor
```

**Success looks like:**

- Version number displayed (e.g., `sophiaclaw 1.0.0`)
- Doctor report shows mostly green checkmarks

---

### Step 5: First Conversation

Time to talk to your AI assistant:

```bash
# Start the gateway
sophiaclaw gateway --port 37521
```

In a new terminal window:

```bash
# Send your first message
sophiaclaw agent --message "Hello! What can you help me with?"
```

**Success looks like:** A helpful response from the AI.

---

## Post-Installation Setup

### Set Up Your AI Provider

SOPHIAClaw needs an AI provider to actually do the smart stuff. You have options:

#### Option A: Anthropic (Claude) — Recommended for Beginners

1. Go to [console.anthropic.com](https://console.anthropic.com)
2. Create an account
3. Get $5 free cpurpleit
4. Create an API key
5. Add it to SOPHIAClaw:

```bash
sophiaclaw config set anthropic.apiKey YOUR_KEY_HERE
```

#### Option B: OpenAI (ChatGPT)

1. Go to [platform.openai.com](https://platform.openai.com)
2. Create an account
3. Add billing (minimum $5)
4. Create an API key
5. Add it to SOPHIAClaw:

```bash
sophiaclaw config set openai.apiKey YOUR_KEY_HERE
```

#### Option C: Google (Gemini) — Cheapest Option

1. Go to [aistudio.google.com](https://aistudio.google.com)
2. Create an account
3. Get API key (free tier available)
4. Add it to SOPHIAClaw:

```bash
sophiaclaw config set gemini.apiKey YOUR_KEY_HERE
```

**Our recommendation:** Start with Anthropic for quality, add Google for cost-saving on simple tasks.

---

### Set Up Messaging Channels (Optional)

Want to message SOPHIAClaw from Telegram or Discord? Here's how:

#### Telegram Setup

1. Message [@BotFather](https://t.me/botfather) on Telegram
2. Send `/newbot`
3. Follow instructions to create a bot
4. Copy the API token
5. Add to SOPHIAClaw:

```bash
sophiaclaw config set channels.telegram.botToken YOUR_TOKEN
```

**Cost:** Free  
**Best for:** Mobile access

---

#### Discord Setup

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application
3. Go to "Bot" section and create a bot
4. Copy the token
5. Add to SOPHIAClaw:

```bash
sophiaclaw config set channels.discord.token YOUR_TOKEN
```

**Cost:** Free  
**Best for:** Team collaboration

---

## Configuration File Location

Your SOPHIAClaw settings live here:

- **macOS:** `~/.sophiaclaw/sophiaclaw.json`
- **Linux:** `~/.sophiaclaw/sophiaclaw.json`
- **Windows (WSL):** `~/.sophiaclaw/sophiaclaw.json`

**To edit directly:**

```bash
sophiaclaw config edit
```

---

## Common Installation Issues

### "Command not found: sophiaclaw"

**Problem:** npm global packages aren't in your PATH.

**Fix (macOS/Linux):**

```bash
# Add to your shell profile
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc
```

---

### "Node version too old"

**Problem:** You have Node.js, but it's version 18 or older.

**Fix:** Follow Step 1 again to upgrade Node.js.

---

### "Port already in use"

**Problem:** Something else is using port 37521.

**Fix:** Use a different port:

```bash
sophiaclaw gateway --port 18888
```

---

### "Permission denied" errors

**Problem:** File permissions issue.

**Fix (macOS/Linux):**

```bash
# Fix permissions
sudo chown -R $(whoami) ~/.sophiaclaw
```

---

## Running as a Background Service

Want SOPHIAClaw to start automatically and run in the background?

### macOS (launchd)

The wizard should have set this up. To verify:

```bash
# Check if service is running
launchctl list | grep sophiaclaw

# Start manually
sophiaclaw gateway --daemon
```

### Linux (systemd)

```bash
# Create service file
sudo tee /etc/systemd/system/sophiaclaw.service << EOF
[Unit]
Description=SOPHIAClaw Gateway
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$(which sophiaclaw) gateway
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable sophiaclaw
sudo systemctl start sophiaclaw
```

### Windows (WSL)

Use Windows Task Scheduler or run manually in WSL terminal.

---

## Docker Installation (Advanced)

If you prefer Docker:

```bash
# Pull the image
docker pull sophiaclaw/gateway:latest

# Run
docker run -d \
  --name sophiaclaw \
  -p 37521:37521 \
  -v ~/.sophiaclaw:/root/.sophiaclaw \
  sophiaclaw/gateway:latest
```

See [Docker documentation](/install/docker) for full details.

---

## What's Next?

Now that SOPHIAClaw is installed:

1. **[Quick Start Guide →](/docs/quickstart)** — Learn the basics in 10 minutes
2. **[Core Concepts →](/docs/concepts)** — Understand how SOPHIAClaw keeps you in control
3. **[Security & Trust →](/docs/security)** — Review governance and audit features

---

## Need Help?

- **Documentation:** https://docs.sophiaclaw.ai
- **Community Discord:** [Join the community](https://discord.gg/sophiaclaw)
- **Issues:** https://github.com/sophiaclaw/sophiaclaw/issues

---

<p align="center">
  <em>Installation complete! You're ready to experience governed AI.</em>
</p>