Runbook · Multi-agent software factory
Building software with a team of AI agents: installing ChatDev 2.0 and passing a full-lifecycle smoke test
For a while now I've wanted to break out of the closed ecosystems I write code in every day — OpenAI's ChatGPT and Codex, Anthropic's Claude and Claude Code. The reason is simple: the free, openly available models have been closing the gap with the $20-a-month subscription tiers so quickly that paying for a walled garden increasingly feels like a habit rather than a necessity. That instinct was sharpened by Bill Gurley's July 2026 Washington Post opinion piece — Gurley, president and founder of the P3 Institute and a former venture capitalist, argues that the flood of powerful models being given away for free is not a security threat but ordinary competition: the oldest strategy in software, cost leadership, driving price down toward the near-zero cost of copying a model. It is, in the essay's words, simply "what competition looks like." Convinced that the open side is where the momentum now lies, I went hunting for a serious free-model toolchain to build real software with — and ChatDev is the most promising thing I found.
If this feels familiar, it should: it rhymes with the last great platform war — the walled gardens of Microsoft and Apple against the scrappy openness of GNU and Linux. Open source was written off as a hobbyist's toy and, in Microsoft's infamous verdict, a "cancer" to be excised. Instead it endured and quietly came to run most of the planet's servers, phones, and clouds — the very incumbent that once denounced it now owns GitHub. That open source was not crushed has been a profound and lasting good for humanity, and the same contest now seems to be replaying one level up, in the AI models themselves.
So what is ChatDev? It runs a virtual software company staffed entirely by LLM agents. Rather than one chatbot doing everything, it assigns roles — a chief executive and chief technology officer to shape the design, a programmer to write the code, a reviewer to critique it, and a tester to exercise it — and lets them collaborate, message by message, across a complete software-development lifecycle of designing, coding, reviewing, and testing in iterative loops. Just as importantly, the agents don't merely discuss code; they write it to disk and run it inside their own disposable, virtualized sandbox — an isolated Python environment created fresh for each project — so generated programs can be executed and debugged safely without ever touching the host system. Each run leaves behind a real, self-contained mini-project you can open, inspect, and execute yourself.
What follows is a start-to-finish, copy-paste procedure for standing up ChatDev 2.0 on a fresh Linux machine — from an empty directory to a passing Hello, World! that has been driven through that full lifecycle by the agent graph. The coding model is the latest GLM, served through NVIDIA NIM's OpenAI-compatible endpoint.
A working ChatDev checkout, a reproducible Python environment, the workflow pointed at GLM, and a generated mini-project on disk whose program actually runs. Every step below explains what it does and why, and the final sections show you how to prove the run succeeded and what to do when it doesn't.
My Environment
This procedure was carried out on the machine below. Treat it as the "known-good" baseline — none of the specific versions are mandatory. The only genuine prerequisites are a 64-bit Linux box with sudo/apt access and an internet connection, plus a few gigabytes of free disk and, ideally, 8 GB of RAM. Everything else — git, curl, the build libraries, uv, Python 3.12, and (optionally) Node.js — is installed by the steps that follow.
| Component | Value | Notes |
|---|---|---|
| OS | Ubuntu 26.04 LTS (x86-64) | Fresh desktop install |
| RAM | 8 GB | Upgraded from 3.8 GB; the agents build their own venv and run tests, so headroom matters |
| CPU | 2 cores | Fine — the heavy lifting is remote model inference |
| System Python | 3.14 | Not used directly — the toolchain installs its own 3.12 (see Step 5) |
| Working dir | empty ChatDev folder | Created under the home directory (Step 1) |
You can sit at the machine directly or drive it over SSH — the commands are identical either way.
Create the working directory
Pick a spot under your home directory with a few gigabytes free and make a directory called ChatDev to hold everything. Then move into it — every later command assumes you are in this folder.
mkdir -p ~/dev/ChatDev
cd ~/dev/ChatDevmkdir -p creates the folder (and any missing parents) without complaining if it already exists. Adjust ~/dev/ChatDev to wherever you like — the rest of the guide only cares that you are inside this directory.
Install git, curl, and the build dependencies
We need git to fetch the code (Step 4), curl to fetch the uv installer (Step 3), and a set of C headers/compilers because a few of ChatDev's Python dependencies build native code at install time (PDF/vector rendering via pycairo, and mapping libraries via cartopy). Install them all in one go:
sudo apt-get update
sudo apt-get install -y \
git curl ca-certificates \
build-essential pkg-config python3-dev \
libcairo2-dev libjpeg-dev zlib1g-dev \
libgeos-dev libproj-dev proj-data proj-binIn plain terms: git/curl/ca-certificates are the fetch tools; build-essential + pkg-config + python3-dev are the compiler toolchain; libcairo2-dev/libjpeg-dev/zlib1g-dev satisfy the graphics/PDF stack; libgeos-dev/libproj-dev satisfy the geospatial stack. Getting these in place now means the Python build in Step 5 goes through cleanly.
On many systems git and curl are already present; installing them again is harmless and keeps this procedure self-contained on a truly minimal box.
Install uv, the Python project manager
ChatDev 2.0 is managed with uv — a fast, self-contained tool that resolves dependencies, creates the virtual environment, and can even download the exact Python version the project needs. Install it with the official script:
curl -LsSf https://astral.sh/uv/install.sh | shThe installer drops uv into ~/.local/bin. Make sure that's on your PATH for the current shell (and future ones):
export PATH="$HOME/.local/bin:$PATH"
uv --version # should print something like: uv 0.11.xOpen a new terminal later? Re-run the export PATH=... line, or add it to your ~/.bashrc so uv is always found.
Clone the ChatDev repository
Clone the fork into the current (empty) directory. The trailing dot tells git "clone here" rather than creating a nested ChatDev/ChatDev folder.
git clone https://github.com/tuklusan/ChatDev.git .After this you should see the project files (run.py, pyproject.toml, yaml_instance/, server_main.py, and so on) directly inside your ChatDev folder.
Cloning with . only works into an empty directory. If git refuses, the folder isn't empty — check for stray files with ls -a first.
Build the Python environment with uv sync
One command reads pyproject.toml, creates a project-local virtual environment in .venv/, and installs every dependency:
uv syncThis is where the Step 2 system libraries earn their keep — uv compiles the native packages against them. Expect it to take a few minutes on first run.
The project pins requires-python = ">=3.12,<3.13". If your system Python is newer (mine is 3.14), uv simply downloads and uses a private copy of Python 3.12 for this project. You don't have to install or manage 3.12 yourself — that's a big reason the project standardizes on uv. You can confirm which interpreter it chose with uv run python --version.
Sanity-check that the environment imports the heavy dependencies:
uv run python -c "import openai, faiss, cartopy, fastapi, pydantic; print('core imports OK')"Point ChatDev at your model provider
ChatDev reads the API endpoint and key from a .env file. Start from the template:
cp .env.example .envThen edit .env so it targets NVIDIA NIM's OpenAI-compatible endpoint. Only these two lines matter:
BASE_URL=https://integrate.api.nvidia.com/v1
API_KEY=nvapi-XXXXXXXXXXXXXXXXXXXXXXXXXXXXGet a free nvapi- key by signing in at build.nvidia.com and creating an API key. Paste it in place of the X's above.
The goal is to code with the latest GLM model. GLM is published by Z.ai, and NVIDIA NIM hosts it on an OpenAI-compatible endpoint that supports tool / function calling — which ChatDev's agents rely on heavily. A DeepSeek key, by contrast, only serves DeepSeek's own models, so it can't run GLM. If you have a NIM key, that's the route to GLM.
Select the GLM model in the workflow
ChatDev workflows are YAML files under yaml_instance/. Each agent node names the model it should call. The classic full-lifecycle workflow, ChatDev_v1.yaml, ships pointing at gpt-4o; we swap that for the latest GLM. Back the file up first, then do the replacement:
cp yaml_instance/ChatDev_v1.yaml yaml_instance/ChatDev_v1.yaml.bak
sed -i 's|name: gpt-4o|name: z-ai/glm-5.2|g' yaml_instance/ChatDev_v1.yaml
grep -c 'name: z-ai/glm-5.2' yaml_instance/ChatDev_v1.yaml # expect: 9Here z-ai/glm-5.2 is the model ID exactly as NVIDIA NIM expects it. The workflow's nine agent roles (programmer, code reviewer, tester, and so on) now all use GLM. Note that each node keeps provider: openai and reads base_url: ${BASE_URL} / api_key: ${API_KEY} — those placeholders are filled from your .env at run time, so "openai" here just means "an OpenAI-compatible API," not OpenAI the company.
Model IDs change over time. Check the NVIDIA build catalog for the newest GLM and confirm its card lists tool/function calling support, then use that exact ID in the sed command. A model without tool-calling will fail partway through the run.
Run the full-lifecycle smoke test
Now drive a tiny project through the whole pipeline. run.py loads the workflow and then asks for a task prompt on standard input — so we pipe the prompt straight in and let it run unattended:
export PATH="$HOME/.local/bin:$PATH"
echo "Create a simple Python program that prints Hello, World! to the console." \
| uv run python run.py --path yaml_instance/ChatDev_v1.yaml --name HelloWorldWhat the flags mean:
--path— which workflow graph to execute (the full design → code → review → test lifecycle).--name— a label for this run; it becomes the output folder name.
You'll see a stream of log lines as the agents talk to GLM, write code, review it, and run tests. The result is written under WareHouse/HelloWorld_<timestamp>/. On a small task like this it finishes in a couple of minutes.
For bigger projects, run inside tmux or screen (or prefix with nohup) so the job survives a dropped connection.
Validate the smoke test
A run that completes isn't automatically a run that worked. Here's how to inspect exactly what the agents produced and prove the program runs. First, locate the output folder (it has a timestamp suffix) and capture it in a variable:
RUN=$(ls -d WareHouse/HelloWorld_* | tail -1)
echo "$RUN"
find "$RUN" -maxdepth 2 -type fLook at what the "software company" actually delivered — the generated code lives in code_workspace/:
ls "$RUN/code_workspace"
cat "$RUN"/code_workspace/*.pyThen run the generated program — this is the real smoke test:
cd "$RUN/code_workspace"
python3 main.pyHello, World!Finally, review the run's own bookkeeping. ChatDev writes several artifacts alongside the code:
cd - >/dev/null
cat "$RUN"/token_usage_*.json # tokens spent per agent node
sed -n '1,20p' "$RUN"/workflow_summary.yaml # graph metadata: node/edge counts, model usedWhat a passing run looks like
code_workspace/contains real source files (e.g.main.py,hello_world.py) plus apyproject.tomland amanual.mduser guide.- Running the program prints
Hello, World!with no traceback. workflow_summary.yamlshowsmodel_name: z-ai/glm-5.2on the agent nodes — confirming GLM did the work, not a fallback.token_usage_*.jsonshows non-zero tokens across multiple nodes (a real Hello-World run lands around 80k total tokens), meaning every lifecycle phase actually executed.- No
401/403/429errors in the log stream.
What the smoke test did — and didn't — prove
It did prove: the install is sound, uv's environment works, your NIM key authenticates, GLM is reachable with tool-calling, and the multi-agent graph can run end-to-end and emit runnable code. In this run the reviewer and test loops ran, the agents even spun up an isolated .venv inside code_workspace/ to execute the code, and the final program passed.
It did not prove: that ChatDev handles a complex spec. Hello-World is deliberately trivial — it exercises the plumbing, not the reasoning. It also doesn't touch the optional web console (the Node/npm front-end, see the next step). Treat a green smoke test as "the factory is wired correctly," then scale up to a real task by changing the prompt and --name.
Optional: install Node.js & npm for the web console
The smoke test above needs nothing from Node.js. But ChatDev also ships a browser-based console (a Vite front-end) if you'd rather design and launch workflows from a GUI. That's the only part that needs Node. On Ubuntu 26.04 the distro packages are current enough (Node 22, npm 9), so a plain apt install works:
sudo apt-get install -y nodejs npm
node --version # v22.x
npm --version # 9.xThen install the front-end packages and launch both servers from the repo root:
cd frontend
npm install
cd ..
export PATH="$HOME/.local/bin:$PATH"
make dev # backend on :6400, web console on :5173Open http://localhost:5173 in a browser. If ChatDev is on a remote box, forward the port over SSH first (for example, ssh -L 5173:localhost:5173 -L 6400:localhost:6400 your-host) and then browse to localhost:5173 on your own machine.
If a distro's Node is older than the front-end requires, install a current LTS from NodeSource instead of the apt package.
Troubleshooting
The failures below are the ones you're most likely to hit, roughly in the order they occur along the procedure.
Install & environment
Cause: ~/.local/bin isn't on your PATH in this shell.
Fix: run export PATH="$HOME/.local/bin:$PATH" (and add it to ~/.bashrc). Re-check with uv --version.
Cause: native build dependencies missing — pycairo (pulled in via the PDF stack) can't find Cairo or pkg-config.
Fix: complete Step 2, specifically sudo apt-get install -y pkg-config libcairo2-dev build-essential python3-dev, then re-run uv sync.
Cause: the geospatial system libraries are absent.
Fix: sudo apt-get install -y libgeos-dev libproj-dev proj-data proj-bin, then re-run uv sync.
Cause: uv couldn't fetch the pinned Python (usually no network/egress, or a proxy in the way).
Fix: install it explicitly with uv python install 3.12, or ensure the box can reach the internet, then re-run uv sync.
Cause: you're cloning into a non-empty folder.
Fix: start from an empty directory (check with ls -a), or clone into a fresh subfolder and cd into it.
Model & API
Cause: the API key is missing, wrong, or still the placeholder in .env.
Fix: put a valid nvapi- key in .env as API_KEY=..., confirm BASE_URL=https://integrate.api.nvidia.com/v1, and run from the repo root so .env is picked up.
Cause: a valid key whose organization lacks the "Public API Endpoints" permission for the serverless inference endpoint — a widely reported NIM gotcha.
Fix: in your NVIDIA account, enable public API-endpoint access for the org tied to the key (or generate the key under an org that has it), then retry.
Cause: you hit the free-tier rate limit (roughly ~40 requests/min). Multi-agent runs fire many calls in bursts.
Fix: ChatDev already retries with backoff; for persistent 429s, slow down concurrent work, keep tasks smaller, wait for the limit window to reset, or request a rate-limit increase for your NIM account.
Cause: the chosen model doesn't support tool/function calling, which ChatDev's agents require.
Fix: pick a model whose NVIDIA card lists tool-calling support (the current GLM does), and set that exact ID in ChatDev_v1.yaml (Step 7).
Cause: the model swap in Step 7 didn't apply to every node.
Fix: verify with grep -c 'name: z-ai/glm-5.2' yaml_instance/ChatDev_v1.yaml (expect 9) and grep -n 'name: gpt-4o' yaml_instance/ChatDev_v1.yaml (expect none). Re-run the sed if needed.
Runtime & resources
Cause: not enough RAM — the agents create their own virtual environment and execute the generated code, which needs headroom on top of the run itself.
Fix: give the box ~8 GB of RAM (this is why I upgraded from 3.8 GB), close other memory hogs, or add swap.
Cause: you launched run.py without feeding a prompt on stdin, so it's waiting for keyboard input.
Fix: pipe the task in as shown in Step 8 (echo "..." | uv run python run.py ...), or simply type the prompt and press Enter.
Cause: the run aborted early (usually an auth error before any node produced output), or you're looking in the wrong directory.
Fix: check the log tail for 401/403, fix the key, and confirm you're running from the repo root. Output is created under WareHouse/ there.
And that is the quiet thrill of it: a whole software team — designer, programmer, reviewer, tester — running on a model I didn't rent, on hardware I own, for little more than the cost of the electricity. The open-source insurgency of the last era refused to be crushed and went on to run the world, for the betterment of us all. If that same story is now replaying one level up, in the models themselves, then standing up a free-model software factory on your own Linux box is a small but satisfying way to stand on the open side of it.
References: ChatDev repository · NVIDIA build catalog / API keys · uv documentation.
Model IDs, rate limits, and dependency lists evolve — re-check the model card and the repo's pyproject.toml if something here has drifted since publication.