AI Manus: A Self-Hosted Agent Loop with Docker Sandboxes, but Check the Model Calling Before You Commit

What AI Manus Actually Solves

AI Manus is a general-purpose AI Agent system that runs tools in a sandboxed environment. The problem it addresses is the operational gap between a chatbot and a tool-using agent: you want an LLM to write files, run shell commands, browse the web, and search, but you do not want those actions to touch your host machine. The project gives you a web UI, a backend server, and a per-task Docker sandbox. It is for developers or small teams who want to deploy their own agent infrastructure without paying for a managed agent service. The README positions it as a minimal deployment: only an LLM service is required, with no other external dependencies. That is a strong claim, but the architecture shows you still need Docker, MongoDB, and Redis for session history, so the 'minimal' part refers to the absence of a separate vector database or a dedicated agent orchestration service.

The Plan-and-Execute Loop and Native Tool Calls

The core mechanism is a PlanAct agent. When a user sends a message, the backend forwards it to this agent, which plans and executes steps. The planner and executor submit structured results through native tool calls, not through a fragile JSON-in-prompt protocol. This is a design choice that avoids parsing errors common with prompt-injected JSON. The README explicitly names tools like create_plan and complete_step. The agent can call sandbox tools: Shell, Browser, File, Search, and MCP. All events are streamed back to the web client via WebSocket. The distinction matters: because the plan and step results are structured outputs, the model must support native function calling. Deepseek and GPT models are recommended. If your model does not support tool calling reliably, the whole loop degrades. That is a hard constraint that you should verify against your LLM provider before adopting.

Sandbox Architecture: Docker, VNC, and the Socket Mount

Each task gets a separate sandbox, which is an Ubuntu Docker container. The backend creates this sandbox by talking to the Docker daemon through /var/run/docker.sock. The sandbox starts a Chrome browser and API services for File and Shell tools. For browser viewing, the sandbox runs a headless browser with xvfb and x11vnc, then websockify converts VNC to WebSocket, and the web UI connects via a NoVNC component through the server's WebSocket forward. This is a real architecture, but it carries a security implication: the backend container needs read-write access to the host Docker socket. The docker-compose example mounts it as read-only, but that still gives the backend the ability to create and control containers. If an attacker compromises the backend, they could potentially escape the sandbox. The README does not discuss this risk, so you should assess it yourself.

Getting It Running: Docker Compose and .env

Deployment is straightforward if you have Docker 20.10+ and Docker Compose. The README provides a docker-compose.yml example with two services: frontend and backend. The backend depends on a sandbox service, which is not defined in the example but is implied. You save the YAML, create a .env file based on .env.example, and set at least API_KEY, API_BASE, and MODEL_NAME. Then you run docker compose up -d. The note about sandbox-1 exiting with code 0 is important: that is normal, because the sandbox container may just ensure the image is pulled. For development, you can clone the repo, copy .env.example, and run ./dev.sh up. The debug mode starts one global sandbox and exposes ports for the frontend (5173), backend API (8000), debugpy (5678), sandbox API (8080), VNC (5902), and MongoDB (27017). The dev script also has rebuild commands: ./dev.sh down -v and ./dev.sh b. The configuration surface is small, but you must understand which keys the backend reads.

Session Management and the Library

Task sessions are managed through MongoDB and Redis, which supports background tasks. The sidebar Library aggregates attachments and artifacts across sessions, with type filters, search, per-file favorites, preview, and jump-back to the source task. This is a concrete feature set that goes beyond a simple chat log. It means you can collect outputs from multiple tasks and find them later. The README also mentions stopping and interrupting conversations, plus file upload and download. These are practical features for an agent system where long-running tasks may need manual intervention. The dependency on MongoDB and Redis is worth noting: if you want to run AI Manus in a minimal environment, you cannot skip these services. The roadmap lists completed items like Docker Compose, Settings, and Celery backend, which suggests the project has been evolving, but the current release v2.7.0 includes these features.

Limitations and Wrong-Tool Cases

The most obvious limitation is the dependency on the Docker socket. If you are in a Kubernetes environment or a managed container platform where you cannot mount /var/run/docker.sock, AI Manus will not work as designed. The roadmap explicitly lists K8s and Docker Swarm multi-cluster deployment as future work, so current versions are single-host only. Another limitation is the model requirement: the README warns that reliable tool calling is needed, and only Deepseek and GPT are recommended. If you are using a smaller open-weights model that struggles with structured outputs, the plan-and-execute loop will fail or produce malformed steps. The README also notes that in debug mode only one sandbox is started globally, which means concurrent tasks are not isolated during development. This is a real constraint for testing. Finally, the 'minimal deployment' claim is misleading if you interpret it as 'no infrastructure': you still need MongoDB and Redis, though the README does not list them in the environment requirements section, only in the feature list.

Alternatives: Comparing Approaches

A direct alternative is the original Manus, which is a hosted agent service, but AI Manus is a rebuild with a web UI and sandbox, as the blog post title suggests. Another alternative is to build your own agent loop using LangChain directly, without the sandbox layer. That approach would give you full control over the execution environment but would require you to implement sandboxing, session storage, and a web UI yourself. The difference in approach is that AI Manus bundles the sandbox and the UI, so you get a turnkey system, but you inherit its architectural choices, such as the Docker socket mount and the VNC-based browser viewing. A third alternative is a tool like OpenHands, which also uses Docker sandboxes for coding agents, but OpenHands focuses on software development tasks, while AI Manus is general-purpose. The trade-off is specialization versus generality. If you only need coding agents, a specialized tool may be more mature; if you need browser, file, and search tools in one system, AI Manus offers that out of the box.

Maintenance and Upgrade Cost

The project is actively maintained, with recent releases v2.7.0 on 2026-08-12, v2.6.0 on 2026-08-02, and v2.5.0 on 2026-07-19. The release cadence is roughly monthly, which means you should expect regular updates. The upgrade path is not documented in the README, but since the project uses Docker Compose, you likely need to pull new images and restart services. The dev script provides rebuild commands, but for production you would need to handle image pulls. The configuration is centralized in .env, so changes between versions may introduce new keys. The MIT license is permissive, but you must retain the license notice. There is no mention of a migration guide, so you should check the docs for breaking changes before upgrading. The roadmap indicates ongoing work, so the project is not stagnant, but that also means the API may shift.

Editorial conclusion

Adopt AI Manus if you already run Docker 20.10+ and a LangChain-compatible model with reliable tool calling, and if you want a self-hosted agent with browser, shell, and file tools isolated per task. Skip it if you cannot mount /var/run/docker.sock or if you need multi-cluster orchestration, since the roadmap lists K8s and Docker Swarm support as future work. Before adopting, verify that your chosen model reliably emits native tool calls, because the entire plan-and-execute flow depends on structured output tools like create_plan and complete_step, not JSON-in-prompt. Also confirm the sandbox image pull behavior, because the README notes that a sandbox container exiting with code 0 is normal, which could confuse operators unfamiliar with the pattern.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes