ditto-os 0.1.0

A powerful Rust-based browser automation framework
Documentation

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

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

Using Docker

From Docker Hub (Recommended)

docker pull dittoos/ditto:latest
docker run -p 8080:8080 dittoos/ditto:latest

From GitHub Container Registry

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

cargo run

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

2. Create a Mirror Agent

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

# 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):

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:

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:

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

cargo test

Code Formatting

cargo fmt

Linting

cargo clippy

Building for Release

cargo build --release

🐳 Docker Development

Build Image

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

Run Container

# 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

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 file for details.

🙏 Acknowledgments

📞 Support

Ditto - Making browser automation simple and powerful 🚀