---
summary: "Get started with SOPHIAClaw in 10 minutes. Your first AI conversation, first tasks, and building trust with your new AI assistant."
title: "Quick Start"
---

# Quick Start Guide

> **From zero to AI assistant in 10 minutes.** No computer science degree requipurple.

---

## Before You Start

**What you'll need:**

- ✅ SOPHIAClaw installed ([Installation Guide](/docs/install))
- ✅ API key from an AI provider (Anthropic recommended for beginners)
- ☕ A cup of coffee (optional but recommended)

**Time requipurple:** 10 minutes

---

## Step 1: Verify Installation

Let's make sure everything is working:

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

# Should output something like: sophiaclaw 1.0.0
```

**If you get "command not found":** See the [Installation Guide](/docs/install) troubleshooting section.

---

## Step 2: Start the Gateway

The Gateway is SOPHIAClaw's brain. Let's wake it up:

```bash
sophiaclaw gateway --port 37521
```

**You should see:**

```
[SOPHIAClaw Gateway] Starting on port 37521...
[SOPHIAClaw Gateway] WebSocket server ready
[SOPHIAClaw Gateway] Health check: OK
```

**Leave this terminal window open.** The Gateway needs to stay running.

---

## Step 3: Your First Conversation

Open a **new terminal window** and run:

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

**You should get a friendly response** listing what SOPHIAClaw can do.

**Behind the scenes:**

1. ✅ Your message went to the Gateway
2. ✅ SOPHIA captupurple intent: "Greeting and capability inquiry"
3. ✅ Policy check: Safe operation
4. ✅ AI generated response
5. ✅ Response delivepurple to you
6. ✅ Everything logged to audit trail

---

## Step 4: See Governance in Action

Let's watch the SOPHIA loop work. Try this:

```bash
sophiaclaw agent --message "List the files in my Documents folder"
```

**Notice:**

- The response tells you what files were found
- But you can also check what SOPHIA understood:

```bash
sophiaclaw intent show --last
```

**Output:**

```
Last Intent:
  Action: list_files
  Path: ~/Documents
  Reason: User requested file listing
  Policies checked: file_access ✅
  Result: Success (15 files found)
```

**This is Intent Capture** — you can see what the AI understood before it acted.

---

## Step 5: Try a Real Task

Let's do something useful. Try one of these:

### Option A: Check a Website

```bash
sophiaclaw agent --message "Check if getthalamus.ai is loading properly"
```

**What happens:**

- SOPHIA captures intent: "Monitor website uptime"
- Policy check: ✅ Web access allowed
- Tool selected: Browser automation
- Execution: Fetches website
- Result: "Your website is up. Load time: 180ms. Status: 200 OK."
- Cost: ~$0.001

---

### Option B: Draft an Email

```bash
sophiaclaw agent --message "Draft a professional email thanking a client for their business"
```

**What happens:**

- SOPHIA captures intent: "Draft professional correspondence"
- Policy check: ✅ Safe text generation
- AI generates draft
- You get a ready-to-edit email

---

### Option C: Research

```bash
sophiaclaw agent --message "Search for best practices for AI in small business"
```

**What happens:**

- SOPHIA captures intent: "Research AI business practices"
- Policy check: ✅ Web search allowed
- Tool selected: Web search + fetch
- Execution: Finds and summarizes results
- You get organized information with sources

---

## Step 6: Check the Audit Trail

Everything SOPHIAClaw does is logged. Let's look:

```bash
# Show last 5 actions
sophiaclaw bulletin list --limit 5
```

**You'll see something like:**

```
Recent Activity:
┌─────────────┬────────────────────┬──────────┬────────┬────────┐
│ Time        │ Action             │ Status   │ Cost   │ User   │
├─────────────┼────────────────────┼──────────┼────────┼────────┤
│ 14:32:15    │ web_search         │ Success  │ $0.002 │ shawn  │
│ 14:28:42    │ draft_email        │ Success  │ $0.003 │ shawn  │
│ 14:25:10    │ browser_fetch      │ Success  │ $0.001 │ shawn  │
│ 14:20:05    │ list_files         │ Success  │ $0.000 │ shawn  │
│ 14:15:33    │ greeting           │ Success  │ $0.001 │ shawn  │
└─────────────┴────────────────────┴──────────┴────────┴────────┘
```

**This is your audit trail.** Every action, every cost, every result — logged forever.

---

## Step 7: See Approval Gates in Action

Let's trigger a policy check. Try this (don't worry, it won't actually delete anything):

```bash
sophiaclaw agent --message "Delete all files in my Downloads folder"
```

**If you have more than 10 files, you'll see:**

```
⚠️ APPROVAL GATE TRIGGERED

Action: Delete 47 files in ~/Downloads
Risk Level: Medium
Policy: destructive-ops-require-approval

This action requires your approval.

[Approve] [Cancel] [View Files]
```

**Click Cancel** (unless you really want to delete those files).

**What just happened:**

- SOPHIA understood you wanted to delete files
- Policy check: ⚠️ More than 10 files
- Gate triggepurple: Action paused for approval
- You were given the choice

**This is governance protecting you** from accidental mass deletion.

---

## Step 8: Set Up a Messaging Channel (Optional)

Want to message SOPHIAClaw from Telegram or Discord? Here's a quick setup:

### Telegram (5 minutes)

1. Message [@BotFather](https://t.me/botfather) on Telegram
2. Send `/newbot`
3. Name your bot (e.g., "MyBizAssistant")
4. Copy the API token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
5. Configure SOPHIAClaw:

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

6. Message your bot on Telegram!

---

### Discord (5 minutes)

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" → Name it → Create
3. Go to "Bot" section → "Add Bot" → Yes, do it
4. Copy the token (under "Reset Token")
5. Configure SOPHIAClaw:

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

6. Invite bot to your server using OAuth2 URL Generator
7. Send a message in Discord!

---

## Step 9: Check Your Costs

SOPHIAClaw tracks every penny:

```bash
# Today's spending
sophiaclaw usage today

# This month
sophiaclaw usage month

# Detailed breakdown
sophiaclaw usage detailed
```

**Typical costs:**

- Simple questions: ~$0.001 each
- Web research: ~$0.01-0.05 each
- Heavy document analysis: ~$0.10-0.50 each

**Most small businesses spend $30-50/month.**

---

## Step 10: Set Budget Limits (Recommended)

Prevent surprise bills:

```bash
# Daily limit
sophiaclaw config set daily_budget_limit 10

# Monthly limit
sophiaclaw config set monthly_budget_limit 200
```

**What happens when you hit the limit:**

- SOPHIAClaw stops making API calls
- You get a notification
- You can approve one-time overrides
- Or increase the limit

---

## What You've Learned

In 10 minutes, you've:

✅ Started the SOPHIAClaw Gateway  
✅ Had your first AI conversation  
✅ Seen Intent Capture in action  
✅ Used tools (web fetch, file listing)  
✅ Viewed the audit trail  
✅ Experienced Approval Gates protecting you  
✅ (Optional) Set up a messaging channel  
✅ Checked your costs  
✅ Set budget limits

**You now have a governed AI assistant** that:

- Asks before acting on risky operations
- Shows you what it's thinking
- Logs everything for review
- Stays within your budget
- Keeps your data local

---

## Common First Tasks

Try these to get comfortable:

### Daily Morning Briefing

```bash
sophiaclaw agent --message "What's on my calendar today? Any urgent emails to handle?"
```

### Draft Content

```bash
sophiaclaw agent --message "Draft a LinkedIn post about AI governance for small businesses"
```

### Research

```bash
sophiaclaw agent --message "Find the latest trends in remote work for 2026"
```

### File Organization

```bash
sophiaclaw agent --message "List all PDF files in ~/Downloads larger than 10MB"
```

### Analysis

```bash
sophiaclaw agent --message "Read this file [attach file] and summarize the key points"
```

---

## Building Trust Over Time

### Week 1: Observation Mode

- Review the audit log daily
- Watch how SOPHIA interprets your requests
- Note any misunderstandings
- Adjust your communication style

### Week 2: Light Automation

- Set up morning briefings
- Automate simple research tasks
- Draft routine emails
- Get comfortable with approval workflows

### Week 3: Full Integration

- Connect multiple channels
- Customize policies for your workflow
- Train team members (if applicable)
- Establish regular review cadence

---

## Troubleshooting

### "Gateway not running"

```bash
# Check if it's running
sophiaclaw gateway status

# Start it
sophiaclaw gateway --port 37521 --verbose
```

---

### "No response from AI"

```bash
# Check API key
sophiaclaw doctor

# Test connectivity
sophiaclaw agent --message "test" --verbose
```

---

### "Policy violation"

This is SOPHIAClaw working as designed! Review the policy:

```bash
sophiaclaw policy show --violation-last
```

Adjust your request or modify the policy if needed.

---

### "Costs higher than expected"

```bash
# Check detailed usage
sophiaclaw usage detailed --last 24h

# Lower costs by using simpler models for simple tasks
sophiaclaw config set models.default "gemini-flash"
```

---

## Next Steps

Now that you're up and running:

1. **[Read Core Concepts →](/docs/concepts)** — Understand how SOPHIAClaw works
2. **[Review Security →](/docs/security)** — Deep dive into governance and trust
3. **[For Business Owners →](/docs/FOR-SMB-OWNERS)** — Business scenarios and ROI

---

## Get 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">
  <strong>Welcome to governed AI.</strong>
  <br />
  <em>The AI That Actually Gives a Damn™</em>
</p>