# 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 🚀