# OpenCastor

**The Universal Runtime for Embodied AI.**

> Stop writing boilerplate. Start building robot agents.

OpenCastor connects any AI model to any robot hardware through a single YAML config file. Swap brains (Claude, Gemini, GPT, Ollama) or bodies (Raspberry Pi, Jetson, Arduino) without changing a line of code.

Whether you have a $50 Amazon robot kit or a $50,000 industrial arm, OpenCastor makes it work.

## Why OpenCastor?

| Feature | What it means |
|---|---|
| **Universal Adapter** | Switch between Claude, Gemini, GPT, or Ollama with one config change |
| **Hardware Agnostic** | Built-in drivers for PCA9685, Dynamixel, Serial, and more |
| **Zero Friction** | Unbox to agent in under 5 minutes |
| **Safety First** | Hard-coded safety layers prevent LLM hallucinations from causing physical damage |
| **RCAN Compliant** | Built on the open [RCAN Standard](https://rcan.dev/spec/) for interoperability |
| **Messaging Built-in** | Control your robot via WhatsApp, Telegram, Discord, or Slack |

## Quick Start

### 1. Install

**Linux / macOS (one-liner):**
```bash
curl -fsSL https://raw.githubusercontent.com/craigm26/OpenCastor/main/scripts/install.sh | bash
```

**Windows 11 (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/craigm26/OpenCastor/main/scripts/install.ps1 | iex
```

**Manual install (any platform):**
```bash
git clone https://github.com/craigm26/OpenCastor.git
cd OpenCastor
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
```

<details>
<summary>Platform-specific notes</summary>

| Platform | Package Manager | Notes |
|---|---|---|
| **macOS** | Homebrew (auto-installed) | Apple Silicon & Intel supported |
| **Ubuntu / Debian** | apt | Includes RPi auto-detection |
| **Fedora / RHEL** | dnf | |
| **Arch Linux** | pacman | |
| **Alpine** | apk | |
| **Raspberry Pi** | apt | Enables I2C & camera automatically |
| **Windows 11** | winget / choco | Native PowerShell, no WSL needed |

**Installer flags:** `--dry-run` (preview), `--no-rpi` (skip RPi detection), `--skip-wizard`

**Verify installation:** `bash scripts/install-check.sh` (or `install-check.ps1` on Windows)
</details>

### 2. Run the Wizard

```
$ castor wizard

OpenCastor Setup Wizard v2026.2.17.11

Which Brain do you want to use?
[1] Anthropic Claude Opus 4.6 (Recommended)
[2] Google Gemini 2.5 Flash
[3] Google Gemini 3 Flash (Preview)
[4] OpenAI GPT-4.1
[5] Local Llama (via Ollama)

> Selection: 1
```

The wizard generates an RCAN config file, collects your API key, and optionally sets up messaging channels.

### 3. Run

```bash
castor run --config my_robot.rcan.yaml
```

Your robot is now online. Open `http://localhost:8501` for the CastorDash web interface.

## Swap Your Brain in One Line

Your robot's entire personality lives in a YAML config file powered by the [RCAN Standard](https://rcan.dev/spec/). Switch AI providers by editing one block:

```yaml
# Option A: Anthropic Claude (Recommended)
agent:
  provider: "anthropic"
  model: "claude-opus-4-6"       # Best reasoning & safety

# Option B: Google Gemini
# agent:
#   provider: "google"
#   model: "gemini-2.5-flash"    # Stable. Also: gemini-2.5-pro, gemini-3-flash-preview

# Option C: OpenAI GPT
# agent:
#   provider: "openai"
#   model: "gpt-4.1"             # 1M context, strong vision. Also: gpt-5

# Option D: Local / Offline
# agent:
#   provider: "ollama"
#   model: "llava:13b"
#   url: "http://localhost:11434"
```

## Architecture

```
[ WhatsApp / Telegram / Discord / Slack ]   <-- Messaging Channels
                    |
            [ API Gateway ]                 <-- FastAPI (castor gateway)
                    |
      [ Claude / Gemini / GPT / Ollama ]    <-- The Brain (Provider Layer)
                    |
              [ RCAN Config ]               <-- The Spinal Cord (Validation)
                    |
        [ PCA9685 / Dynamixel / GPIO ]      <-- The Nervous System (Drivers)
                    |
              [ Your Robot ]                <-- The Body
```

- **Messaging Channels**: Control your robot from WhatsApp, Telegram, Discord, or Slack.
- **API Gateway**: FastAPI server with REST endpoints, webhook receivers, and bearer-token auth.
- **Provider Layer**: Normalizes AI outputs into a standard `Thought` object (text + action JSON).
- **RCAN Validation**: Checks actions against physical constraints (speed limits, range of motion, collision).
- **Driver Layer**: Translates high-level intent (`move_forward`) into low-level signals (PWM, serial, I2C).

## Supported Models (Feb 2026)

| Provider | Models | Best For |
|---|---|---|
| **Anthropic** | `claude-opus-4-6`, `claude-sonnet-4-5-20250929` | Reasoning, safety, complex planning |
| **Google** | `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-3-flash-preview`, `gemini-3-pro-preview` | Video, multimodal, speed |
| **OpenAI** | `gpt-4.1`, `gpt-4.1-mini`, `gpt-5` | Instruction following, 1M context |
| **Ollama** | `llava:13b`, any local model | Privacy, offline, no API cost |

## Supported Hardware

Pre-made RCAN presets for popular kits, or bring your own config:

| Kit | Price | Preset |
|---|---|---|
| Waveshare AlphaBot / JetBot | ~$45 | `presets/waveshare_alpha.rcan.yaml` |
| Adeept RaspTank / DarkPaw | ~$55 | `presets/adeept_generic.rcan.yaml` |
| SunFounder PiCar-X | ~$60 | `presets/sunfounder_picar.rcan.yaml` |
| Robotis Dynamixel (X-Series) | Varies | `presets/dynamixel_arm.rcan.yaml` |
| DIY (ESP32, Arduino, custom) | Any | Generate with `castor wizard` |

## The Perception-Action Loop

OpenCastor runs a continuous observe-reason-act cycle:

1. **Observe** -- capture camera frame + sensor telemetry
2. **Reason** -- send to AI model, receive structured action JSON
3. **Act** -- translate intent into motor commands with safety checks
4. **Repeat** -- configurable latency budget (default 200ms)

```python
from castor.providers import get_provider
from castor.drivers.pca9685 import PCA9685Driver

brain = get_provider(config["agent"])
driver = PCA9685Driver(config["drivers"][0])

while True:
    frame = camera.capture()
    thought = brain.think(frame, "Sort the recycling from the trash.")
    if thought.action:
        driver.move(thought.action.get("linear", 0), thought.action.get("angular", 0))
```

## Docker

```bash
cp .env.example .env                          # Add your API keys
cp config/example.rcan.yaml config/robot.rcan.yaml  # Or use castor wizard
docker compose up                             # Launch API + dashboard

# Or with a custom command:
docker compose run opencastor castor wizard   # Interactive setup
docker compose --profile gateway up           # Include messaging gateway
```

## CLI Reference

### Setup
```bash
castor wizard                                      # Interactive setup wizard
castor quickstart                                  # One-command: wizard + demo
castor configure --config robot.rcan.yaml          # Interactive config editor
castor install-service --config robot.rcan.yaml    # Generate systemd unit file
castor learn                                       # Interactive step-by-step tutorial
```

### Run
```bash
castor run       --config robot.rcan.yaml          # Perception-action loop
castor run       --config robot.rcan.yaml --simulate  # No hardware
castor gateway   --config robot.rcan.yaml          # API gateway + messaging
castor dashboard                                   # Streamlit web UI
castor demo                                        # Simulated demo (no hardware/API keys)
castor shell     --config robot.rcan.yaml          # Interactive command shell
castor repl      --config robot.rcan.yaml          # Python REPL with robot objects
```

### Diagnostics
```bash
castor doctor                                      # System health checks
castor fix                                         # Auto-fix common issues
castor status                                      # Provider/channel readiness
castor logs -f                                     # Structured colored logs
castor lint      --config robot.rcan.yaml          # Deep config validation
castor benchmark --config robot.rcan.yaml          # Performance profiling
castor test                                        # Run test suite
```

### Hardware
```bash
castor test-hardware --config robot.rcan.yaml      # Test motors individually
castor calibrate --config robot.rcan.yaml          # Interactive calibration
castor record    --config robot.rcan.yaml          # Record a session
castor replay    session.jsonl                     # Replay a recorded session
castor watch     --gateway http://127.0.0.1:8000   # Live telemetry dashboard
```

### Config Management
```bash
castor migrate   --config robot.rcan.yaml          # Migrate RCAN config version
castor backup                                      # Back up configs
castor restore   backup.tar.gz                     # Restore from backup
castor export    --config robot.rcan.yaml          # Export config bundle (no secrets)
castor diff      --config a.yaml --baseline b.yaml # Compare two configs
castor profile   list                              # Manage named config profiles
```

### Safety & Compliance
```bash
castor approvals                                   # View/approve dangerous commands
castor privacy   --config robot.rcan.yaml          # Show sensor access policy
castor audit     --since 24h                       # View tamper-evident audit log
castor audit     --verify                          # Verify audit chain integrity
```

OpenCastor's safety kernel includes anti-subversion (prompt injection defense), work authorization for destructive actions, physical bounds enforcement (workspace/joint/force limits), tamper-evident hash-chained audit logs, and safety state telemetry at `/proc/safety`. See [`docs/safety-audit-report.md`](docs/safety-audit-report.md) for the full architecture.

### Network & Fleet
```bash
castor discover                                    # Find RCAN peers on LAN
castor fleet                                       # Multi-robot status (mDNS)
castor network   status                            # Network config & Tailscale
castor schedule  list                              # Manage scheduled tasks
```

### Advanced
```bash
castor token     --role operator                   # Issue JWT for RCAN API
castor search    "battery low" --since 7d          # Search operational logs
castor plugins                                     # List loaded plugins
castor upgrade                                     # Self-update + health check
castor update-check                                # Check for newer versions
```

## Contributing

OpenCastor is fully open source (Apache 2.0) and community-driven. We want your help.

**Get involved:**
- **Discord**: [discord.gg/jMjA8B26Bq](https://discord.gg/jMjA8B26Bq) -- chat with maintainers and the community
- **Issues**: [GitHub Issues](https://github.com/craigm26/OpenCastor/issues) -- report bugs or request features
- **PRs**: Fork, branch, and submit -- see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines
- **Twitter/X**: [@opencastor](https://twitter.com/opencastor)

**Areas we need help with:**
- **Driver Adapters**: ODrive, VESC, ROS2 bridges, ESP32 serial
- **AI Providers**: Mistral, Grok, Cohere, local vision models
- **Messaging Channels**: Matrix, Signal, Google Chat
- **Sim-to-Real**: Gazebo / MuJoCo integration
- **Tests**: Unit tests, integration tests, hardware mock tests

Every contribution matters -- from fixing a typo to adding a new driver.

## License

Apache 2.0. Built for the community, ready for the enterprise.

---

*Built on the [RCAN Spec](https://rcan.dev/spec/) by [Continuon AI](https://github.com/craigm26).*
