Super Agent Party: a self-hosted AI companion that runs your desktop

What Super Agent Party actually bundles

Most self-hosted companion projects pick one job. Super Agent Party picks six and ships them in a single Electron shell. The README lists a desktop companion with custom VRM models and 3D scenes, VTube Studio control for Live2D models, a chat interface with tavern character cards and long-term memory, a Task Center for background agent work, computer control through desktop vision plus mouse, keyboard and terminal tools, and one-click deployment to QQ, WeChat, Feishu, DingTalk, Telegram, Discord and Slack. Livestreaming targets Bilibili, YouTube and Twitch, including a 360-degree panoramic mode.

The intended user is someone who wants a local neuro-sama-style setup without wiring five repositories together. The package.json keywords name the audience directly: AI, Multi-Agent, Productivity, Automation, MCP, A2A. If you already run ComfyUI or SillyTavern and want the character layer to sit next to them rather than inside them, this is the category of tool you are looking at.

The Electron shell, the Python backend and port 3456

The repository splits cleanly into a JavaScript front end and a Python service. main.js is the Electron entry point, start.js is the npm start script, and server.py is the backend that the Dockerfile launches. The Dockerfile is explicit about the shape of the process: it installs Node 20 from NodeSource, installs acpx globally with npm, then creates a uv virtual environment and runs uv sync against pyproject.toml and uv.lock.

The backend listens on port 3456. The Dockerfile sets HOST=0.0.0.0, PORT=3456, PYTHONUNBUFFERED=1 and IS_DOCKER=1, and the final command is:

CMD [".venv/bin/python", "server.py", "--host", "0.0.0.0", "--port", "3456"]

In the Docker Compose file the backend container is deliberately not published. Only the gateway container, built from ailm32442/nginx-for-sap, maps 3456:3456 to the host. That gateway carries JWT_SECRET, INIT_USER and INIT_PASS, and a FORCE_RESET flag that the comment says resets the password to root/pass on restart. The design choice here is sound: one exposed port, credentials handled in front of the API rather than inside it. The cost is that the backend is only reachable through that nginx layer, so debugging a failing agent call means going through the gateway or attaching to the sap-backend container.

Python version is pinned hard in pyproject.toml: requires-python = ">=3.12,<3.13". There is no 3.13 support in the declared range. That constraint propagates to anyone building from source.

Installing Super Agent Party on Windows or Docker

The README recommends the Windows portable package over the installer. It is described as installation-free and able to synchronize to the latest version of the repository, so you do not wait for a repackaged desktop build. The release page for v0.4.3 carries super-agent-party-win-v0.4.3.zip, and there is a mirror link on ModelScope for users in China. The stated requirement is Windows 10/11, Windows Server 2025 or later.

Once unzipped, the README says two batch files do the work. Double-click the start script to launch, or the update script to pull the newest version.

一键启动(start).bat
一键更新(update).bat

If you would rather have an installer, the release also publishes Super-Agent-Party-Setup-0.4.3.exe. The README notes one thing during installation: choose to install only for the current user. It does not explain what breaks otherwise, and that is a gap worth knowing about before you click through.

For a server or a machine you do not want to touch, the Compose file is the shorter path. Copy it, then bring it up:

docker compose up -d

After that, the gateway answers on host port 3456. The environment block in the Compose file ships INIT_USER=root and INIT_PASS=pass, and the comment warns to change JWT_SECRET from the placeholder string. Data persists in ./super-agent-data for the backend and ./gateway-data for the gateway, so removing the containers does not remove your chats.

If you are driving this from a CLI agent, the README points at a separate document rather than the main one:

curl -fsSL https://raw.githubusercontent.com/heshengtao/super-agent-party/main/README_AGENT.md

The README states that a CLI agent should read README_AGENT.md and use it to guide the user through installation. That file is the authoritative install path for automation; the main README is written for a human clicking links.

Where the dependency list becomes the limitation

The most concrete constraint in this repository is pyproject.toml. It is long, and it is not long because of one heavy package. It includes faiss-cpu for vector search, rank-bm25 for lexical retrieval, mem0ai pinned to exactly 1.0.0, langchain-community, langchain-openai, langchain-ollama, python-a2a with the all extra, e2b-code-interpreter, discord-py, qq-botpy, lark-oapi, sherpa-onnx, imageio-ffmpeg, pydub, edge-tts, and three separate onnxruntime variants selected by platform: onnxruntime on darwin, onnxruntime-directml on win32, and onnxruntime-gpu elsewhere. pywin32 is pulled in only on Windows.

That means the install is not portable in the way a small service is. A Linux headless deployment gets the GPU onnxruntime path and still carries the Discord, QQ and Feishu bot libraries whether or not you run those bots. The Docker image is built from python:3.12-slim and installs gcc, curl, git and Node 20 on top, so the image is not slim in practice.

The second limitation is documentation depth. The README is a feature gallery with screenshots. It does not document the HTTP surface behind the open OpenAI-compatible API, it does not describe rollback if an update script pulls a broken main, and it does not explain what the FORCE_RESET flag does to existing sessions beyond resetting the credentials. If you need a stable contract to build against, the README does not give you one.

How this differs from SillyTavern and Open WebUI

SillyTavern is the closest comparison for the chat half, and the difference is scope rather than quality. SillyTavern is a front end: it handles character cards, prompts and model connections, and it expects you to bring the rest. Super Agent Party puts the front end, the VRM avatar, the VTube Studio bridge, the IM bots and the agent toolchain in one process. The README even claims compatibility with tavern character cards, so the migration path for a SillyTavern user is importing cards, not rewriting them.

Open WebUI sits at the other end. It is a browser-based chat interface over Ollama and OpenAI-compatible endpoints, and it stays in the browser. Super Agent Party is an Electron desktop application whose README describes phone-sized and capsule-sized docking windows, desktop vision, and control of the mouse, keyboard and terminal. Those are capabilities a browser tab cannot have. The trade is that Open WebUI is straightforward to run as a container behind a reverse proxy, while Super Agent Party's Compose setup routes everything through its own nginx gateway with its own credential store.

For the avatar specifically, the README links a separate repository, heshengtao/sap-live2d, for Live2D extensions. If your interest is only a Live2D model on stream, that extension is the smaller thing to evaluate.

Licence, updates and what maintenance costs you

The licence is AGPL-3.0, declared in both package.json and pyproject.toml. The practical consequence is the one that applies to every AGPL project: if you modify it and let users interact with it over a network, the licence's network clause is the part your legal review will focus on. There is also a LICENSE-third-party/ directory at the top level, which suggests bundled components carry their own terms. That is a question for a lawyer, not for this article.

Upgrade cost depends on which artifact you chose. The portable package is designed to track the repository, and the README says the update script synchronizes to the latest version. That is convenient and it means you are running main, not a tagged release. The desktop installer is pinned to a version, so it moves only when a new installer is published. The last push to the repository was on 2026-08-23, and v0.4.3 was released the same day, so the tagged path and the repository were in step at that point.

There is a maintenance asymmetry worth naming. The project ships releases frequently, and the release notes show large surface changes between them: v0.4.2 added Goal Mode, desktop companion subtitles and expression control, and migratable data; v0.4.1 added WeChat and enterprise WeChat bots, ACP protocol integration with CLI agents, and Vtube Studio control. Features arrive faster than the README documents them, and the README is the only specification published for the project.

Editorial conclusion

Adopt it if you want one local process that owns the avatar, the chat memory, the IM bots and the agent toolchain, and you accept an Electron app on Windows 10/11 with a Python 3.12 backend. Skip it if you need a headless Linux service, a documented REST contract, or a small dependency surface; the pyproject.toml alone pulls in faiss-cpu, sherpa-onnx, onnxruntime, discord-py and pywin32. Before installing, read README_AGENT.md and check whether the release you pick still matches the README, because the portable package updates from main while the desktop installer is pinned to a tagged build.

Frequently asked questions

Official sources

1. heshengtao/super-agent-party on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases