XAgent: an experimental agent that keeps every tool call inside a docker ToolServer
An Autonomous LLM Agent for Complex Task Solving
At a glance
- What is it?
- OpenBMB's XAgent splits work across a dispatcher, a planner and an actor, then does the actual work inside a container that holds a file editor, a Python notebook, a browser, a shell and a Rapid API bridge. It describes itself as experimental, still in early stages, and its own model rules rule out plain gpt-3.5-turbo.
- Who is it for?
- Read it as a research prototype that the authors themselves call experimental, not as an autonomous agent you can hand production work. It suits someone who wants to study the dispatcher, planner and actor split, has two OpenAI keys ready including a 16k backup, and can afford at least six compose services on one machine.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 107 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- OpenBMB/XAgent8,550 ★ · +4
| Repository | 2026-09-12 | 2026-11-15 |
|---|---|---|
| OpenBMB/XAgent | 8.5k | 8.6k |
4 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Every action happens inside the ToolServer container
The safety story is structural rather than policy based. ToolServer is a docker container that holds the environment the agent acts in, and the stated design goal is that all actions are constrained inside it, which is the reason the project says you can run it anyway. Inside that container sit five tools: a file editor for writing, reading and modifying files, an interactive Python notebook for running code and drawing figures, a web browser for searching and visiting pages, a bash shell that can execute any shell command including installing programs and hosting services, and a Rapid API bridge for calling external APIs. The consequence for readers is that the container is the entire blast radius, and the shell tool is broad enough to install packages and start services inside it rather than merely read a file.
Only the actor touches tools, and the planner can rewrite milestones
The design splits into three named parts. The dispatcher dynamically instantiates tasks and dispatches them to different agents, and it is the place where new agents are added and existing ones improved. The planner generates and rectifies plans, divides a task into subtasks, and produces milestones so agents can work step by step. The actor conducts the actions, uses the various tools to finish a subtask, and can bring a human into the loop when it hits a wall. The consequence is a separation of concerns you can build on, and also a constraint: adding capability means touching the actor's tool set and the dispatcher's agent list, not editing one monolithic loop, and a plan that gets rectified mid run changes milestones the actor was already working against.
Plain gpt-3.5-turbo is ruled out on context length alone
Model choice is treated as a hard requirement rather than a preference, and the guidance is specific. The recommendation is gpt-4-32k, gpt-4 is described as acceptable for most simple tasks, and at least one gpt-3.5-turbo-16k key has to be present as a backup model. The plain gpt-3.5-turbo variant is neither tested nor recommended because its context length is minimal, and the instruction is not to try running XAgent on it. Keys live in assets/config.yml, which must be configured before a run, and at least one OpenAI key is needed to reach the API. The consequence for anyone budgeting or reproducing a run is that a working setup costs two keys across two model tiers, not one, and swapping in a cheaper model is exactly the path the project warns against.
One compose file drags in mongo, mysql and redis
A local run is not a single container. Docker and docker-compose are installed first, and the ToolServer image is either pulled or built from the local sources with:
docker compose build
docker compose upThe compose file then defines ToolServerManager on port 8080, a ToolServerNode, a db service on mongo, XAgentServer, and an xagent-mysql service, with an xagent-redis service that XAgentServer references in its environment and depends on. ToolServerManager mounts the host docker socket into the container, so it can talk to the docker daemon, and it is started with two workers and a 600 second timeout in its command. XAgentServer is named XAgent-Server, reads its environment from a .env file, mounts the assets directory read only, and publishes ports 5173 and 8090; it also declares dependencies on mysql and redis with a health condition, and its database URL carries root credentials inline. The consequence is a footprint of at least six services on one machine, and credentials written into a committed file.
The ToolServerNode service is labelled as never used by XAgent
One detail in the compose file deserves attention because it sits oddly against the rest of the documentation. The ToolServerNode service carries an inline comment stating that it creates a test node that will never be used by XAgent. Elsewhere the run notes describe a workflow in which, after execution, the entire workspace held in ToolServerNode is copied into running_records. Both statements come from the repository itself, and the effect for a reader is a real question about which node actually holds your files: the service the compose file says is unused is the one the run notes describe as the source of the workspace copy. Treat the path of your output files as something to verify on your machine rather than assume.
Records reproduce a run only against the same code version
Run history is a first class feature, and it comes with an explicit limit. After execution, intermediate step information is written into running_records, including task statuses, the LLM's input and output pairs, and the tools used. A former run can be replayed by pointing record_dir at a record, and that setting defaults to Null in the config. The catch is stated plainly: a record is a system level recording tied to the code version of XAgent, and it documents the running config, the query, code execution statuses including errors, and server behaviour. The consequence is that a record shared with a colleague running a different commit may not reproduce, which makes records good for debugging your own failure and shaky as a portable artifact. Sensitive information, API keys included, is stripped before writing, so a record can be shared.
Two front doors, and the config path needs a container restart
XAgent can be driven from the command line or through a browser interface. The GUI runs in the XAgentServer container, started with nginx and a web server listening on port 5173, which is where you point a browser locally. The command line entry point is run.py, which takes a task string and a config file, and an optional upload files argument lets you hand the agent starting files instead of describing them.
pip install -r requirements.txtpython run.py --task "put your task here" --config-file "assets/config.yml"Generated files accumulate in the local_workspace directory during a run. There is also a second, less obvious path: if you want XAgentServer to read a different config file, you change the CONFIG_FILE value in the .env file and restart the docker container, so a config switch is not a per run flag.
One release tag, and setup.py declares no command
Packaging is thinner than the architecture suggests. The only release is v1.0.0, published on 2023-11-22, and the version field in setup.py still reads 1.0.0 while the default branch has seen commits since, the most recent push to main dated 2026-07-31. setup.py calls setup with a name, that version, and packages from find_packages, with no console script entry declared, so installing the package gives you an importable tree rather than an xagent command; you invoke the agent through run.py and the compose services instead. The repository is Apache-2.0 licensed and ships English, Chinese and Japanese readmes, plus XAgent, XAgentGen, XAgentServer and XAgentWeb directories alongside ToolServer and dockerfiles.
Editorial conclusion
Read it as a research prototype that the authors themselves call experimental, not as an autonomous agent you can hand production work. It suits someone who wants to study the dispatcher, planner and actor split, has two OpenAI keys ready including a 16k backup, and can afford at least six compose services on one machine. Do not expect reliability claims, a packaged command line, or records that reproduce across code versions, and check the docker socket mount and the root credentials in the compose file before putting anything you care about inside it.
Frequently asked questions
what is xagent
XAgent is an open source experimental LLM driven autonomous agent built to solve tasks automatically. It is described as general purpose and still in its early stages, and it is composed of a dispatcher, a planner and an actor, with all actions constrained inside a docker ToolServer container.
what is trellix xagent
Nothing in this repository describes a Trellix product by that name. Here XAgent is the OpenBMB project: a Python agent for complex task solving, licensed under Apache-2.0, whose work happens in a ToolServer container reached through a manager service on port 8080.
What does XAgent need installed before the first run?
Docker and docker-compose come first, then the ToolServer image is started with docker compose up, or built locally with docker compose build followed by docker compose up. Python 3.10 or newer is required on the host side, dependencies come from pip install -r requirements.txt, and at least one OpenAI key must be placed in assets/config.yml before run.py is invoked.
Which model does XAgent need and why two keys?
The guidance recommends gpt-4-32k, allows gpt-4 for most simple tasks, and requires at least one gpt-3.5-turbo-16k key as a backup model. The plain gpt-3.5-turbo variant is not tested or recommended because of its minimal context length, so a working configuration carries keys at two different tiers.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openbmb-xagent)Star history chart for your README
[](https://hysenlabs.com/projects/openbmb-xagent)Was this useful?