ManusX - Open Source General-Purpose AI Agent

English | 中文 | 📚 Documentation

ManusX is a fully privately deployable enterprise-grade AI Agent system that runs various tools and operations in isolated sandbox environments.

Build your own AI agent with complete control over your data - no external dependencies required!

🎯 Why ManusX?

• 🏢 Enterprise-Ready: Fully private deployment with no data leakage
• 🔧 Extensible: Built-in Skill system and MCP protocol support
• 🔒 Secure: Docker sandbox isolation for each task
• 🚀 Simple: Minimal setup - only requires an LLM API
• 🌍 Universal: Compatible with OpenAI, Anthropic, DeepSeek, and more

✨ Key Features

🎥 Demo

Browser Automation

Skill System

🚀 Quick Start

Prerequisites

• Docker 20.10+ and Docker Compose
• LLM API (OpenAI, Anthropic, DeepSeek, or OpenAI-compatible)
• 8GB+ RAM recommended

One-Command Deployment

# Clone the repository
git clone https://github.com/nuoyimanaituling/manus-x.git
cd manus-x

# Configure environment variables
cp .env.example .env
# Edit .env and set your API_KEY, API_BASE, MODEL_NAME

# Start all services
./run.sh up -d

# Visit http://localhost:5173

That's it! Your ManusX instance is now running! 🎉

Key Configuration

Edit .env file with your settings:

Note: For complete environment variable list, see .env.example

🏗️ Architecture

System Overview

flowchart TB
    subgraph Frontend["🖥️ Frontend"]
        UI["💬 Web UI"]
        NoVNC["🖼️ NoVNC"]
    end

    subgraph Backend["⚙️ Backend"]
        API["🔌 REST API"]
        subgraph Agent["🤖 PlanAct Agent"]
            Planner["📋 Planner"]
            Executor["⚡ Executor"]
        end
        Tools["🔧 Tools"]
    end

    subgraph Sandbox["📦 Sandbox"]
        Shell["💻 Shell"]
        File["📁 File"]
        Chrome["🌐 Chrome"]
        VNC["🖥️ VNC"]
    end

    subgraph Storage["💾 Storage"]
        MongoDB[("🍃 MongoDB")]
        Redis[("⚡ Redis")]
    end

    UI -->|HTTP| API
    API -->|SSE| UI
    NoVNC -.->|WebSocket| VNC
    API --> Agent
    Planner <--> Executor
    Executor --> Tools
    Tools --> Sandbox
    API --> Storage

Request Flow

1. User sends a message to Frontend
2. Frontend sends HTTP request to Backend
3. Backend creates a Docker Sandbox for the task
4. Plan-Act Agent analyzes the task and generates an execution plan
5. Execution Agent calls tools (Browser/Shell/File) in the Sandbox
6. Real-time events stream back to Frontend via SSE
7. User sees live updates and can interact with tools

Backend Architecture (DDD)

ManusX follows Domain-Driven Design principles:

• Interface Layer (interfaces/): FastAPI routes and API schemas
• Application Layer (application/): Service orchestration
• Domain Layer (domain/):
  • Models: Plan, Step, Message, Skill
  • Agents: Planner Agent, Execution Agent
  • Tools: Browser, Shell, File, Search, Message
• Infrastructure Layer (infrastructure/):
  • LLM: OpenAI, Anthropic implementations
  • Sandbox: Docker container management
  • Database: MongoDB and Redis adapters

🛠️ Tech Stack

Frontend

• Framework: Vue 3 (Composition API) + TypeScript + Vite
• UI: Tailwind CSS + shadcn-vue
• Code Editor: Monaco Editor
• Remote Desktop: NoVNC (WebSocket-based VNC client)
• Internationalization: vue-i18n

Backend

• Framework: FastAPI + Python 3.11+
• Architecture: Domain-Driven Design (DDD)
• Database:
  • MongoDB (sessions, messages, files)
  • Redis (cache, pub/sub, task queue)
• LLM Clients: OpenAI SDK, Anthropic SDK
• Async: Motor (MongoDB), aioredis

Sandbox

• Base Image: Ubuntu 22.04
• Browser: Google Chrome with CDP (Chrome DevTools Protocol)
• Process Manager: Supervisor
• Services:
  • FastAPI server (8080) - Shell/File APIs
  • VNC Server (5900) - Remote desktop
  • Chrome (9222) - CDP debugging
  • WebSockify (5901) - VNC-to-WebSocket proxy

Infrastructure

• Container: Docker + Docker Compose
• CI/CD: GitHub Actions
• Registry: Docker Hub (dockerdockerdockerxzw)

👨‍💻 Development

Start Development Environment

# Start all services with hot reload
./dev.sh up

# View logs
./dev.sh logs -f [backend|frontend|sandbox]

# Stop services
./dev.sh down

# Rebuild after dependency changes
./dev.sh down -v && ./dev.sh build && ./dev.sh up

Exposed Ports in Development Mode:

• 5173 - Frontend (Vite dev server)
• 8000 - Backend API
• 8080 - Sandbox API
• 5900 - Sandbox VNC
• 9222 - Chrome DevTools Protocol

Backend Testing

cd backend

# Run all tests
pytest

# Run specific test file
pytest tests/test_api_file.py

# Run specific test
pytest tests/test_api_file.py::test_name

# Run with coverage
pytest --cov=app tests/

Frontend Development

cd frontend

# Start dev server
npm run dev

# Build for production
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

Project Structure

manusx/
├── frontend/                 # Vue 3 Frontend
│   ├── src/
│   │   ├── pages/           # Page components
│   │   ├── components/      # Reusable components
│   │   ├── api/            # API client
│   │   └── locales/        # i18n translations
│   └── package.json
│
├── backend/                 # FastAPI Backend
│   ├── app/
│   │   ├── domain/         # Domain Layer
│   │   │   ├── models/     # Domain models
│   │   │   └── services/   # Domain services
│   │   │       ├── agents/ # Planner & Execution agents
│   │   │       └── tools/  # Tool implementations
│   │   ├── application/    # Application Layer
│   │   ├── infrastructure/ # Infrastructure Layer
│   │   └── interfaces/     # Interface Layer (API routes)
│   ├── skills/            # Skill definitions
│   └── requirements.txt
│
├── sandbox/                # Docker Sandbox
│   ├── Dockerfile
│   └── supervisord.conf
│
├── docs/                   # Documentation
├── docker-compose.yml     # Production deployment
├── docker-compose-development.yml  # Development
├── .env.example           # Environment template
├── dev.sh                 # Development script
└── run.sh                 # Production script

🚢 Deployment

Production Deployment

# Using run.sh script
./run.sh up -d

# Or using docker-compose directly
docker compose up -d

Building Custom Images

# Set your registry and tag
export IMAGE_REGISTRY=your-registry-url
export IMAGE_TAG=v1.0.0

# Build images
./build.sh

# Push to registry
./run.sh push

Kubernetes Deployment

For Kubernetes deployment, see our K8s deployment guide.

Environment-Specific Configuration

Development (.env.development):

NODE_ENV=development
API_BASE=http://localhost:8000
LOG_LEVEL=DEBUG

Production (.env.production):

NODE_ENV=production
API_BASE=https://your-domain.com/api
LOG_LEVEL=INFO

❓ FAQ

SEARCH_PROVIDER=bing
BING_SEARCH_KEY=your-bing-api-key

backend/skills/my-skill/
├── SKILL.md          # Skill definition (YAML frontmatter + Markdown)
├── scripts/          # Executable scripts
├── references/       # Reference documentation
└── assets/           # Static assets (templates, configs)

---
name: my-skill
description: Brief description of what this skill does
---

# My Skill Title

Detailed instructions for the LLM on how to use this skill...

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

volumes:
  - ./mcp_config.json:/app/mcp_config.json

MCP_CONFIG_PATH=/app/mcp_config.json

AUTH_PROVIDER=password
JWT_SECRET_KEY=your-random-secret-key
PASSWORD_SALT=your-password-salt

AUTH_PROVIDER=local
LOCAL_AUTH_EMAIL=admin@example.com
LOCAL_AUTH_PASSWORD=your-secure-password

AUTH_PROVIDER=none

🤝 Contributing

We welcome contributions from the community!

How to Contribute

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. ✅ Commit your changes (git commit -m 'Add some amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🎉 Open a Pull Request

Development Guidelines

• Follow PEP 8 for Python code
• Use TypeScript for all new frontend code
• Write tests for new features
• Update documentation for user-facing changes
• Keep commits atomic and well-described

Found a bug?

Open an issue with:

• Bug description
• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Docker version, etc.)

💬 Community & Support

• 📝 Documentation: Full Docs
• 💬 Discussions: GitHub Discussions
• 🐛 Bug Reports: GitHub Issues

Need Help?

1. Check the Documentation
2. Search existing issues
3. Ask in GitHub Discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Star History

Made with ❤️ by the ManusX Team

_{If you find this project useful, please give it a ⭐️!}