# Ditto - Mirror Your Web World

A powerful Rust-based browser automation framework that perfectly replicates and controls web browser actions through a RESTful API and WebSocket interface. **Ditto** - because your automation should be an exact copy of what you'd do manually.

## 🚀 Features

- **Perfect Mirror**: Browser automation that mimics human interaction precisely
- **RESTful API**: Complete HTTP API for all browser operations
- **WebSocket Support**: Real-time bidirectional communication
- **Skill System**: Extensible skill-based automation framework
- **Agent Management**: Multi-agent support with authentication and authorization
- **Rate Limiting**: Built-in rate limiting and security features
- **Cross-Platform**: Works on Windows, Linux, and macOS

## 🛠️ Tech Stack

- **Backend**: Rust with Axum web framework
- **Browser Control**: Headless Chrome and WebDriver integration
- **Authentication**: JWT-based auth system
- **Real-time**: WebSocket connections for live updates
- **Containerization**: Docker support with multi-arch builds

## 📦 Installation

### From Source

```bash
git clone https://github.com/ditto-os/ditto.git
cd ditto
cargo build --release
```

### Using Docker

#### From Docker Hub (Recommended)
```bash
docker pull dittoos/ditto:latest
docker run -p 8080:8080 dittoos/ditto:latest
```

#### From GitHub Container Registry
```bash
docker pull ghcr.io/ditto-os/ditto:master
docker run -p 8080:8080 ghcr.io/ditto-os/ditto:master
```

## 🏃‍♂️ Quick Start

### 1. Start Your Mirror

```bash
cargo run
```

The Ditto server will start on `http://localhost:8080`

### 2. Create a Mirror Agent

```bash
curl -X POST http://localhost:8080/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mirror-agent",
    "name": "My Mirror Agent",
    "description": "An agent that perfectly mirrors web interactions"
  }'
```

### 3. Mirror Browser Actions

```bash
# Navigate to a website (just like you would)
curl -X POST http://localhost:8080/api/v1/agents/mirror-agent/sessions/session-123/execute \
  -H "Content-Type: application/json" \
  -d '{
    "action": "navigate",
    "parameters": {
      "url": "https://example.com"
    }
  }'

# Take a perfect screenshot
curl -X POST http://localhost:8080/api/v1/agents/mirror-agent/sessions/session-123/execute \
  -H "Content-Type: application/json" \
  -d '{
    "action": "screenshot",
    "parameters": {
      "path": "mirror-screenshot.png"
    }
  }'
```

## 📚 API Documentation

### Authentication

All API requests require authentication using a Bearer token (your Ditto access key):

```bash
curl -H "Authorization: Bearer YOUR_DITTO_TOKEN" http://localhost:8080/api/v1/agents
```

### Mirror Endpoints

#### Agents (Your Mirror Controllers)
- `GET /api/v1/agents` - List all mirror agents
- `POST /api/v1/agents` - Create a new mirror agent
- `GET /api/v1/agents/:id` - Get mirror agent details
- `PUT /api/v1/agents/:id` - Update mirror agent

#### Mirror Sessions
- `POST /api/v1/agents/:id/sessions` - Create mirror session
- `GET /api/v1/agents/:id/sessions` - List agent mirror sessions
- `GET /api/v1/agents/:id/sessions/:session_id` - Get mirror session details
- `DELETE /api/v1/agents/:id/sessions/:session_id` - Close mirror session

#### Mirror Actions
- `POST /api/v1/agents/:id/sessions/:session_id/execute` - Execute mirror command

#### Skills (Mirror Capabilities)
- `GET /api/v1/skills` - List available mirror skills
- `POST /api/v1/skills` - Create a new mirror skill
- `GET /api/v1/skills/:id` - Get skill details
- `POST /api/v1/skills/:id/execute` - Execute a mirror skill

#### System Health
- `GET /api/v1/health` - Ditto health check
- `GET /api/v1/stats` - Mirror system statistics

### WebSocket (Real-time Mirroring)

Connect to WebSocket for real-time mirror updates:

```javascript
const ws = new WebSocket('ws://localhost:8080/ws/agents/mirror-agent');
ws.onmessage = function(event) {
    console.log('Mirror update:', JSON.parse(event.data));
};
```

## 🔧 Configuration

The Ditto server can be configured through environment variables:

```bash
export DITTO_HOST=0.0.0.0
export DITTO_PORT=8080
export DITTO_ENABLE_CORS=true
export DITTO_JWT_SECRET=your-ditto-secret-key
```

## 🧪 Development

### Running Tests

```bash
cargo test
```

### Code Formatting

```bash
cargo fmt
```

### Linting

```bash
cargo clippy
```

### Building for Release

```bash
cargo build --release
```

## 🐳 Docker Development

### Build Image

```bash
# Build locally
docker build -t dittoos/ditto:latest .
```

### Run Container

```bash
# From Docker Hub
docker run -p 8080:8080 dittoos/ditto:latest

# Or from GHCR
docker run -p 8080:8080 ghcr.io/ditto-os/ditto:master
```

### Deploy to Cloud

The image is available on both registries and can be deployed to any container hosting service:

- **Docker Hub**: `dittoos/ditto:latest`
- **GitHub Container Registry**: `ghcr.io/ditto-os/ditto:master`

### Development with Docker Compose

```bash
docker-compose up --build
```

## 📊 Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP Client   │    │  WebSocket      │    │   Skill Engine  │
│                 │    │  Client         │    │                 │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────┴─────────────┐
                    │      Ditto Server         │
                    │   (Axum + WebSocket)      │
                    └─────────────┬─────────────┘
                                 │
          ┌──────────────────────┼──────────────────────┐
          │                      │                      │
    ┌─────┴─────┐        ┌───────┴──────┐      ┌───────┴──────┐
    │   Agent   │        │   Browser    │      │  Security   │
    │  Manager  │        │   Manager    │      │   Module    │
    └───────────┘        └──────────────┘      └──────────────┘
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request to https://github.com/ditto-os/ditto

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Axum](https://github.com/tokio-rs/axum) - Web framework
- [Headless Chrome](https://github.com/atroche/rust-headless-chrome) - Browser automation
- [Serde](https://github.com/serde-rs/serde) - Serialization
- [Tokio](https://github.com/tokio-rs/tokio) - Async runtime

## 📞 Support

- 📧 Email: support@ditto.dev
- 💬 Discord: [Join our Discord](https://discord.gg/ditto)
- 📖 Documentation: [docs.ditto.dev](https://docs.ditto.dev)

---

**Ditto** - Making browser automation simple and powerful 🚀
