# NekroAgent: a multi-platform agent framework that runs model-written code in a sandbox

> NekroAgent pairs an adapter layer for QQ, Discord, Telegram, Minecraft, Bilibili Live, WeChat, Email and SSE with a core engine that executes AI-generated code in containers. It is aimed at people running bots in group chats, not at single-user CLI assistants.

**KroMiose/nekro-agent** — NekroAgent 是一个面向多人互动场景的跨平台 Agent 框架，集 Claude Code 沙盒执行、工作区编排、长期记忆、结构化 MCP 管理与可视化控制台于一体，兼具高扩展性、多模态交互、实时状态推送和自动化运行能力。项目支持 QQ、Discord、Telegram、Minecraft、BilibiliLive、WeChat、Email、SSE(SDK) 等多种平台接入，应用于构建高智能聊天机器人，可扩展为具备代码执行、工具调用、插件协作和复杂任务处理能力的通用 Agent 系统

- Repository: https://github.com/KroMiose/nekro-agent
- Website: https://nekro.ai
- Stars: 1,126 · Forks: 86
- Language: Python
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/kromiose-nekro-agent

## The problem NekroAgent solves: one agent brain, many chat platforms

Most chat-bot projects pick a platform first and grow an agent around it. NekroAgent inverts that. The README describes the core as designed around input and output streams: an adapter only has to receive messages from a platform and send messages back, and everything else (channel management, plugin execution, sandbox calls) is handled by the core engine. The project ships adapters for OneBot v11 (QQ), Discord, Telegram, Minecraft, Bilibili Live, WeChat through WeChatPad, Email over SMTP and IMAP, and an SSE plus SDK option, with more listed as under development. The intended user is someone operating a bot inside multi-user group chats, where several people talk at once and the agent has to keep track of who said what. The README calls this native multiplayer scenario interaction and lists it as a core capability rather than an add-on. If your use case is one person at a terminal asking a model questions, the adapter layer and channel bookkeeping are overhead you will pay for and never use.

## How the engine works: adapters in, dispatcher out, sandbox in the middle

The architecture diagram in the README shows a two-layer split. Below is the adapter layer, one adapter per external platform. Above is the core engine, which starts with an input stream named collect_message, passes messages to a dispatcher, hands them to shared services (channels, plugins, sandbox), and finally writes to an output stream named forward_message that fans back out to the adapters. The interesting part sits in the shared services. Rather than calling tools directly, the prompt system guides the model to generate code, that code runs in a containerised sandbox, and it talks to the real environment over RPC. That is the mechanism behind the plugin system: a plugin can register key-node callbacks, inject prompt text, and define custom sandbox methods. The dependency list in pyproject.toml confirms the shape of this: aiodocker for container control, openai for model calls, tortoise-orm with asyncpg and psycopg2-binary for PostgreSQL, qdrant-client for vector storage, and mcp for Model Context Protocol services. The sandbox is not decorative. It is the boundary between generated code and your host, and the RPC hop is what lets a plugin expose a method the generated code can call without giving that code direct filesystem access.

## Installing NekroAgent and running the first bot

The README points to the quick-start documentation for Linux, Windows and macOS, and offers a one-command deployment script as the recommended path. The command below fetches install.sh from the repository and passes --with-napcat, which the README says starts a fully automatic standard deployment; without that flag the script runs interactively and asks you to answer Y to install Napcat.

```bash
sudo -E bash -c "$(curl -fsSL https://raw.githubusercontent.com/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat
```

If GitHub is unreachable, the README gives a Cloudflare mirror endpoint for the same script, with the same argument:

```bash
sudo -E bash -c "$(curl -fsSL https://ep.nekro.ai/e/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat
```

For a container-based setup you can instead pull an image. The README documents two tags published to both Docker Hub and GHCR: latest for stable releases cut from tags, and preview built automatically on every main branch update. It recommends latest for production.

```bash
docker pull kromiose/nekro-agent:latest
docker pull kromiose/nekro-agent:preview
```

Once running, the API documentation is served only when the --docs flag is enabled, at http://localhost:8021/api/docs for Swagger UI and http://localhost:8021/api/redoc for ReDoc. The default exposed port in .env.example is NEKRO_EXPOSE_PORT=8021. The README does not document a rollback procedure for a failed deployment, so plan to keep your data directory before upgrading.

## Developing against NekroAgent without the container script

The repository ships a development path that skips the install script. .env.example states the three steps: bring up the dev compose file, copy the example environment file, and run the task runner through uv. The example file targets a PostgreSQL instance on port 5433 and a Qdrant instance on http://127.0.0.1:6334, both preconfigured for the dev Docker services.

```bash
docker compose -f docker/docker-compose.dev.yml up -d
cp .env.example .env.dev
uv run poe dev
```

The environment variables are prefixed NEKRO_ throughout. Database and vector-store connections are toggled by NEKRO_USE_ENV_DATABASE and NEKRO_USE_ENV_QDRANT, and the dev file sets NEKRO_ADMIN_PASSWORD=admin and a fixed JWT secret, which is fine for a local machine and wrong for anything reachable. Note the port difference between the two paths: the dev example uses PostgreSQL on 5433 while the exposed web port stays 8021, so do not assume the compose file and the install script produce identical layouts.

## Where NekroAgent is the wrong tool, and what the documentation leaves open

The sandbox is the feature and the constraint. Because the agent's primary action is generating code that runs in a container and reaches the host over RPC, you need a working Docker environment and enough container resources for concurrent conversations. On a small VPS running several busy group chats, that is a real cost, and the README offers no sizing guidance. The preview features carry a similar caveat: the workspace and Claude Code sandbox system, the Memory System with entities, relations, paragraphs, episodes and vector retrieval, structured MCP registry management, and the rebuilt command system are all labelled preview in the README and described as living on main or preview branches. The preview Docker tag is built from every main update, so pulling it means accepting unreviewed changes. There is also a Python version ceiling that will bite people on new machines: pyproject.toml declares requires-python = ">=3.11,<3.13", so Python 3.13 is excluded even though it is current. Finally, the licence is declared as Custom License in pyproject.toml and the repository metadata carries no standard identifier, so anyone who needs a known OSI licence has to read LICENSE themselves before adopting.

## NekroAgent compared with a plain NoneBot2 bot

The closest comparison is not another agent framework but the plugin ecosystem NekroAgent is built on. Its dependencies include nonebot2 with the FastAPI extra, nonebot-adapter-onebot and nonebot-adapter-minecraft, and the README traces the project's lineage to an earlier NoneBot plugin, Naturel GPT. A conventional NoneBot2 bot handles messages in Python you wrote: the bot author decides what happens, and the model, if present at all, produces text. NekroAgent moves the decision into the model, which writes code the sandbox executes, with plugins contributing callbacks and prompt injections rather than full handlers. The trade is control for reach. A NoneBot2 bot cannot improvise a data transformation it was never written for; NekroAgent can, at the price of a container round trip, a prompt engineering layer you have to tune, and a failure mode where the generated code is wrong. If your bot's behaviour is fixed and small, the conventional approach is cheaper to run and far easier to reason about.

## Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-08-27. Release cadence in the recent history is roughly one feature release per quarter: v2.2.0 on 2026-01-31, v2.3.0 on 2026-04-18, and v2.4.0 on 2026-08-16. Each carries a thematic name in the release notes rather than a changelog summary, so reading the diff or the documentation is the only way to know what moved. Upgrades have two tracks. Pulling kromiose/nekro-agent:latest gives you tag-based stable builds, but you inherit whatever schema changes the release made; the repository contains a migrations directory and aerich is a declared dependency, which indicates Tortoise ORM migrations are part of the flow, though the README does not document an upgrade command. The preview tag is rebuilt on every main update and the README recommends it only for testing and development. On licensing, pyproject.toml states license = {text = "Custom License"} and the repository root holds a LICENSE file; the README and metadata do not summarise its terms, so treat the terms as something to read rather than assume.

## Conclusion

Adopt NekroAgent if you already run a chat bot community and want model-written code, plugins and a WebUI behind one core engine; skip it if you need a single-user CLI agent or a permissively licensed dependency, because pyproject.toml declares license = Custom License and the repository ships no OSI identifier. Verify the custom licence text in LICENSE and your Python version against requires-python = ">=3.11,<3.13" before you commit.

## FAQ

### Which chat platforms does NekroAgent support?

The README lists OneBot v11 (QQ), Discord, Telegram, Minecraft, Bilibili Live, WeChat through WeChatPad, Email over SMTP and IMAP, and SSE plus SDK, with more adapters described as under development. Each platform is handled by an adapter that implements message input and output, while the core engine handles channels, plugins and sandbox calls.

### What Python version does NekroAgent require?

pyproject.toml declares requires-python = ">=3.11,<3.13", so Python 3.11 and 3.12 are supported and 3.13 is excluded. The README badge also shows python 3.11 or newer.

### How do I run NekroAgent without the install script?

.env.example gives three commands: docker compose -f docker/docker-compose.dev.yml up -d, then cp .env.example .env.dev, then uv run poe dev. The example file points at PostgreSQL on 127.0.0.1:5433 and Qdrant on http://127.0.0.1:6334.

### Is NekroAgent's licence an open source licence?

pyproject.toml declares license = {text = "Custom License"} and the repository metadata carries no standard licence identifier. The terms live in the LICENSE file at the repository root and are not summarised in the README.

## Sources

- [Issues](https://github.com/KroMiose/nekro-agent/issues)
- [KroMiose/nekro-agent on GitHub](https://github.com/KroMiose/nekro-agent)
- [Project website](https://nekro.ai)
- [README](https://github.com/KroMiose/nekro-agent/blob/main/README.md)
- [Releases](https://github.com/KroMiose/nekro-agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kromiose-nekro-agent