MultiGen: a self-hosted Planner plus ReAct agent stack you run with Docker Compose

What MultiGen solves, and who it is built for

Most agent demos assume the model provider also hosts the execution. MultiGen takes the opposite position. It is a general-purpose agent platform intended for fully private, on-premise deployment, so the model calls, the tool calls and the files produced along the way stay on hardware you own. The README describes it as a self-hosted alternative to hosted agent products, with the data, the model and the stack under your control.

The audience is narrow but real. You need someone comfortable running Docker Compose, editing a YAML config and pointing an API key at an OpenAI-compatible endpoint. You do not need to write agent code, because the Planner and ReAct loop ship as part of the platform. The repository is Python, licensed MIT, and the API package in pyproject.toml declares requires-python >=3.12 even though the README badge says Python 3.11+. That mismatch is worth resolving against your own interpreter before you plan a deployment.

The problem it addresses is capability sprawl. A single agent that browses, runs shell commands, generates images and writes slide decks needs a lot of tools wired together. MultiGen ships those tools, a sandbox to run them in, and a session store so the results can be replayed.

The Planner and ReAct split, and where the sandbox sits

The architecture is two-stage. A Planner agent takes the user goal and emits a JSON plan of sub-steps. A ReAct agent then picks up each step and iterates: reason, call a tool, observe the result, continue. The README's worked example walks through a paper-reading task where the plan is fetch URL, browse page, download PDF, extract content, summarize, and the ReAct loop then issues browser.goto, browser.snapshot, browser.download and file.read in sequence.

Every shell, browser and file action runs inside an isolated Ubuntu plus Chrome plus VNC container. The README states plainly that the model cannot touch your host. That is the load-bearing design decision. It means the agent's reach is bounded by the container image and the network policy you give it, not by the model's willingness to stay in scope.

Around that core sit the supporting services. Postgres holds session state and generated files are mirrored locally and to Tencent COS for replay and sharing. Redis backs the queue and cache layer. Nginx fronts the stack. Tool calls stream to a Next.js frontend over SSE, with discriminated events for plan, step, tool and message, so the UI can render intermediate reasoning rather than only the final answer. External reach comes through MCP for tools and A2A for delegating sub-tasks to peer agents.

Installing MultiGen from master and running a first task

The README gives one command path for local Docker deployment, and it is explicit that you should use the master branch for evaluation and development. Clone the repository and bring the stack up. The build step compiles the API and sandbox images, so the first run takes a while.

# Local Docker deployment, use master
git clone https://github.com/LiXiaoYaoCareFree/MultiGen.git
cd MultiGen
docker compose up -d --build

Before you start, copy the environment template and fill in the values you actually have. The example file lists database, Redis, Tencent COS and sandbox settings, along with LLM provider configuration. The README says any OpenAI-compatible provider works, including DeepSeek, Volcengine, SiliconFlow, Qwen, OpenAI, vLLM and Ollama, and that you select one by editing config.yaml.

cp .env.example .env

The compose file defines the services you should see after startup: multigen-redis, multigen-postgres, multigen-sandbox, multigen-api and, further down the file than the excerpt shows, the UI and Nginx. The sandbox publishes port 8080 by default, controlled by SANDBOX_PORT, and its healthcheck curls http://127.0.0.1:8080/api/supervisor/status. If that endpoint does not answer, the agent has nowhere to run tools.

docker compose ps
docker compose logs -f multigen-sandbox

Once the sandbox reports healthy and the API is up, open the UI and submit a task. The README's screenshots show sessions for research, PDF merging, SQLite plus FAISS vectorization and image generation, so a reasonable first test is a browsing task that returns a file you can inspect. Watch the center column: you should see a JSON plan appear first, then tool events as the ReAct agent works through it.

Where MultiGen is the wrong tool

The branch policy is the sharpest constraint. MultiGen ships two long-lived branches, master for local Docker deployment and online for public or production environments. The README warns in bold that you should never deploy master to a public or production environment, and that only online is verified for that. If your plan is to stand this up on a public host, you are not following the documented path for the branch you cloned.

The second constraint is operational weight. This is not a library you import. It is Postgres, Redis, a sandbox container, an API, a Next.js frontend and Nginx, all coordinated by Compose. If you wanted a single Python process that calls a model and runs one tool, MultiGen is several orders of magnitude more machinery than the task requires.

The third is the sandbox's own surface. The compose file publishes the sandbox on port 8080 and the environment template exposes SANDBOX_HTTP_PROXY, SANDBOX_HTTPS_PROXY and SANDBOX_CHROME_ARGS. Isolation protects your host from the model, but the sandbox still reaches the network by whatever route you configure. The README does not document a rollback procedure for a bad session, and it does not describe how generated files are purged from Tencent COS. Treat both as open questions to answer before you put real data through it.

How MultiGen differs from a plain LangGraph or ReAct loop

If you have already built an agent with LangGraph or a hand-rolled ReAct loop, the honest comparison is not capability but packaging. A LangGraph graph gives you explicit control over nodes, edges and state, and it runs in your process. You decide where tools execute, and if you want isolation you add it yourself. MultiGen makes the opposite trade: it fixes the topology as Planner plus ReAct, and in exchange it hands you the sandbox, the session store, the streaming UI and the MCP and A2A connectors already assembled.

The .env.example still carries a RECURSION_LIMIT setting described as the LangGraph multi-step reasoning recursion ceiling, so the project has not abandoned that lineage. What it adds is the boundary. In a bare ReAct loop, a shell tool runs wherever the process runs. In MultiGen, the same tool call lands in a container that also hosts Chrome and a VNC server, which is why the README can claim the model cannot touch your host.

That difference matters most for teams that need to show an auditor where agent actions execute. It matters least for teams optimizing for latency or for embedding an agent inside an existing service, where the extra hop to a sandbox container is pure overhead.

Maintenance, upgrade cost and what the MIT licence does not settle

The last push to this repository was on 2026-07-30, and the repository is not archived. There are no releases retrieved, so upgrades happen by pulling the branch rather than by pinning a version. That shifts real work onto you: the online branch is described as carrying hotfixes and deployment configs verified online, and the README tells you to keep production in sync by pulling from online only. Diverging between the two branches is the failure mode to avoid, because master is where development happens and online is where the production fixes land.

The dependency set in pyproject.toml is broad and moving: FastAPI, SQLAlchemy, Alembic, asyncpg, Playwright, the Docker SDK, the MCP SDK and the Tencent COS SDK all carry lower-bound version constraints rather than pins, with uv.lock as the lockfile. If you deploy from the lockfile you get reproducibility; if you resolve fresh you get whatever those lower bounds allow. The restore-business-data.sh script at the repository root suggests the maintainers expect data restore to be a routine operation, though the README does not document it.

MIT covers the code. It does not cover the model you point it at, the Tencent COS bucket you mirror files to, or the terms of the image, video and TTS providers named in the environment template. Those are separate agreements, and the README does not discuss them. This is not legal advice; read the licence file and your provider contracts yourself.

Editorial conclusion

Adopt MultiGen if you need the agent loop, the browser and shell tools and the generated files to stay on infrastructure you control, and if you are willing to run the online branch for anything public. Skip it if you want a managed service or a single-process library you can import into an existing Python app. Before committing, verify three things yourself: that your LLM endpoint is OpenAI-compatible and configured in config.yaml, that the sandbox container's healthcheck at http://127.0.0.1:8080/api/supervisor/status passes on your host, and that you have read the branch table, because the README warns against deploying master to a public environment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lingyuanli/MultiGen on GitHub
4. Project website
5. README