Documentation

Everything you need to get started with Captain Claw.

Installation

Using pip (recommended)

terminal

$ pip install captain-claw

Using Docker

terminal

$ docker run -d -p 23080:23080 \

-v $(pwd)/config.yaml:/app/config.yaml:ro \

-v $(pwd)/.env:/app/.env:ro \

-v $(pwd)/docker-data:/root/.captain-claw \

kstevica/captain-claw:latest

Requirements

  • Python 3.11 or higher
  • At least one LLM API key (OpenAI, Anthropic, Google, or Ollama for local)

Quick Start

1. Start the web server

$ captain-claw-web

Server running at http://localhost:23080

2. Configure on first run

On first launch, Captain Claw runs an interactive onboarding wizard that helps you configure your LLM providers. You can re-run it anytime with captain-claw --onboarding.

3. Open the workspace

Navigate to http://localhost:23080 in your browser. You'll see the home dashboard with access to Chat, Computer workspace, Orchestrator, Brain Graph, and all other modules.

Configuration

Captain Claw uses a YAML configuration file with environment variable overrides. Configuration is loaded in this order (later sources override earlier ones):

  1. ./config.yaml — project root
  2. ~/.captain-claw/config.yaml — home directory
  3. Environment variables
  4. .env file
  5. Built-in defaults

Model Configuration

config.yaml

model:

provider: "openai"

model: "gpt-4o"

temperature: 0.7

max_tokens: 32000

allowed:

- id: "claude-sonnet"

provider: "anthropic"

model: "claude-sonnet-4-20250514"

See the Configuration Reference for all available options.

Built-in Tools

Captain Claw comes with 31 built-in tools organized by category:

File & System

  • shell — Execute terminal commands
  • read — Read files
  • write — Create or append files
  • edit — In-place file editing
  • glob — Pattern matching

Web & Documents

  • web_fetch — Extract text from URLs
  • web_search — Web search via Brave
  • pdf_extract — PDF to markdown
  • docx_extract — Word to markdown
  • xlsx_extract — Excel to tables

Media & Communication

  • image_gen — Generate images
  • image_ocr — OCR from images
  • send_mail — Email via SMTP/Mailgun
  • stt — Speech to text
  • pocket_tts — Text to speech

Memory & Data

  • todo — Cross-session task list
  • contacts — Address book
  • datastore — SQLite tables
  • playbooks — Orchestration patterns
  • scripts — File tracking

Guards & Safety

Captain Claw features a three-layer guard system that checks inputs, outputs, and tool executions before they happen:

  • Input guards — Screen user inputs before sending to the LLM
  • Output guards — Check model responses for risks before presenting
  • Script/Tool guards — Validate shell commands and tool calls before execution

Each guard can operate in ask_for_approval or stop_suspicious mode.

Docker Deployment

Docker Compose (recommended)

docker-compose.yml

version: "3.8"

services:

captain-claw:

image: kstevica/captain-claw:latest

ports:

- "23080:23080"

volumes:

- ./config.yaml:/app/config.yaml:ro

- ./.env:/app/.env:ro

- ./data:/root/.captain-claw

restart: unless-stopped

Ready to get started?

Try Captain Claw in your browser or install it locally.

Full Demo Computer Mode View on GitHub