Nuwax Agent OS: self-hosted agent platform review and install guide

What Nuwax Agent OS is meant to replace

Most teams that want an agent in production end up stitching together four things: a model gateway, a vector store for retrieval, a plugin or tool runtime, and a sandbox where generated code can execute without touching the host. Nuwax bundles all four behind one deployment. The README describes it as an enterprise-grade AI Agent Development and Operation Platform, and the repository topics list the pieces explicitly: a2a, agent, agent-os, agent-sandbox, agentic, agentic-rag, agentos, chatbot, mcp, rag, skills, workflow.

The target user is not an individual experimenting with prompts. It is a team that has to keep agent data inside its own network. The README's framing is private Agentic AI solutions, and the deployment model matches: you run the stack yourself with Docker Compose rather than pointing at a hosted endpoint. The frontend layer in the architecture diagram reaches users through PC web, H5, mini apps and IM clients including Feishu, DingTalk, WeCom and Slack, which tells you the intended consumption surface is an internal assistant rather than a public chatbot.

That scope is also the main risk. A platform that owns model proxying, memory, knowledge base and plugins is a platform you have to operate. The README gives you the commands to do that, but it does not pretend the operational work is zero.

The three-layer architecture and where the sandbox sits

The architecture diagram in the README splits the system into a frontend layer and an access layer. The frontend layer covers PC Web, H5, Mini App and IM clients. The access layer exposes REST API, long connections and WebSocket. Everything above that line is the same backend serving different client shapes, which is why the IM integrations matter: an agent that answers in Slack is using the same API surface as the web console.

The deployment topology is the more interesting decision. Nuwax splits into two deployable services. The main project service is required. Agent Computer, also called the sandbox, is optional and can be deployed separately across multiple servers. The README states that the main service is configured with one or more Agent Computer addresses, which gives you distributed agent sandbox capability.

That split is deliberate. The sandbox is where agent-generated code runs, and the README notes it includes a personal computer environment that requires more resources. Isolating it onto its own host means a runaway agent process does not compete with the control plane for CPU. The cost is that you now have two deployment targets to patch, and the sandbox address list becomes configuration you must keep in sync. If you deploy only the main service, you lose the sandbox and with it the code-execution side of the agent runtime.

The stack underneath is a UmiJS frontend built with max build, served by Nginx in the provided Dockerfile. That is a standard Chinese enterprise frontend toolchain, and it means the build step is a Node 22 container running yarn install and yarn build:prod before the artifact is copied into an Nginx image.

Installing Nuwax with nuwax-cli and Docker

The README points installation at the official nuwax-cli command tool. Before anything else, confirm Docker and Docker Compose V2 are present, because the README calls them core dependencies that must be installed correctly. The verification sequence it gives is short.

docker --version
docker compose version
docker run hello-world

If all three succeed, the environment is ready. The README recommends Ubuntu 22.04 LTS, lists macOS 10.15 and later with OrbStack or Docker Desktop, and states that Windows 10/11 support is coming soon, so Windows is not a working target yet. Hardware guidance is 4 cores and 8GB RAM or higher. On Linux the current user needs Docker permissions, which the README suggests verifying with docker ps.

Main service deployment is documented at nuwax.com/deploy.html rather than inline in the README, so the exact first-run invocation is not in the repository. Once running, service control is uniform.

./nuwax-cli docker-service start
./nuwax-cli docker-service status
./nuwax-cli docker-service restart
./nuwax-cli docker-service stop

A first real use is to bring the stack up, confirm status, then immediately create a backup so you have a known-good restore point before configuring anything.

./nuwax-cli auto-backup run
./nuwax-cli list-backups

The README warns that the backup service requires stopping Docker application servers and recommends running it during low-peak periods. That is a real constraint, not a formality: backups are not online. Restoring uses the backup identifier from the list.

./nuwax-cli rollback [BACKUP_ID]

Upgrading is two commands, and the order matters. The first updates the deployment client itself, the second updates the application service.

./nuwax-cli check-update install
./nuwax-cli auto-upgrade-deploy run

Backup and upgrade are the operational weak points

The README is unusually honest about the backup constraint: the service must be stopped. For a platform holding agent definitions, knowledge base content and memory state, that means every backup is a maintenance window. There is no documented incremental or hot-snapshot path. If your agents serve internal users during business hours, you are choosing between a nightly outage and stale backups.

The upgrade path has a similar shape. auto-upgrade-deploy run automatically detects and downloads new versions for deployment, which is convenient, but the README does not document rollback of a failed upgrade. It documents rollback of backups, which is a different operation: restoring data does not restore the previous application version. The release cadence visible in the repository is fast, with v1.1.13, v1.1.14 and v1.1.16 landing within about two weeks in mid-2026, so upgrade failures are not a hypothetical concern.

The practical reading is that you should take a backup immediately before every auto-upgrade-deploy run, and treat the upgrade as a change that needs a rollback plan you build yourself. Nothing in the README tells you how to pin to a previous version.

There is also a repository-level detail worth noting for anyone building from source. The Makefile contains a merge-apf target that squashes a branch called agent-platform-front into dev as a single commit, with a guard that refuses to run on a dirty working tree. That is an internal workflow artifact, and it suggests the public main branch is not the only line of development.

Where Nuwax is the wrong choice

The clearest boundary is Windows. The README lists Windows 10/11 as support coming soon, and the one-click Docker script only prompts Windows users toward Docker Desktop installation guidance rather than installing anything. If your developers or servers are Windows-first, this is not yet a platform you can standardize on.

The second boundary is the sandbox. If your agents only need retrieval and tool calls against internal APIs, the Agent Computer service is optional and you can skip it, which removes a whole deployment target. But if you do want code execution, you inherit a second stack and the resource profile that comes with it. The README does not publish sandbox isolation guarantees beyond calling it a sandbox and a personal computer environment, so if your threat model requires a documented isolation boundary, that documentation is not in the repository.

The third boundary is scale of operations. There is one backup mechanism with a stop-the-service requirement and no documented hot path. A team that needs continuous availability and point-in-time recovery will find this thin. Nuwax is aimed at internal private deployment where a maintenance window is acceptable, not at a multi-tenant service with an uptime commitment.

Finally, the README does not document a supported Kubernetes deployment path even though the repository contains a k8s/ directory and the Dockerfile references k8s/default.conf.template. The template is an Nginx config, not a manifest set. Anyone expecting a Helm chart should check the docs/ directory before assuming one exists.

How Nuwax differs from Dify and LangFlow

The natural comparison is Dify, which also targets self-hosted agent and LLM application building with Docker Compose. The difference in approach is where the sandbox lives. Dify's model centers on application orchestration and a workflow canvas. Nuwax separates the agent execution environment into its own deployable service that can be spread across multiple servers, which is a distributed-systems answer to the same problem. If you need per-agent isolated compute that scales horizontally, that split is the reason to pick Nuwax. If you want a single Compose file and nothing else, it is extra work.

LangFlow takes a different route again, treating the agent as a visual flow graph. Nuwax is not flow-first. Its topics include workflow, but the README's emphasis is on the operating side: knowledge base management, model proxy, memory system and plugin ecosystem, delivered to web, mobile and IM clients. That is a product for running agents, where LangFlow is closer to a builder for designing them.

The protocol surface is another differentiator. Nuwax lists a2a and mcp among its topics, so agent-to-agent and Model Context Protocol interoperability are in scope. Dify and LangFlow have their own plugin and tool conventions. If MCP compatibility is a requirement for connecting to external tool servers, that is a point in Nuwax's favor, though the README does not spell out which MCP transports are implemented.

Licence, maintenance and what to verify before adopting

Nuwax is licensed under Apache-2.0, and package.json confirms the same identifier for the frontend package, which is published as nuwax-frontend version 1.2.0. Apache-2.0 permits commercial use and modification and includes a patent grant. It also requires that you preserve copyright and licence notices and state significant changes when redistributing. If you fork the frontend and ship it, keep the LICENSE file and the notices intact. This is a description of the licence terms, not legal advice; get counsel to review your specific redistribution plans.

The repository is not archived, and the last push was on 2026-09-10, which is recent. The release history shows a steady patch cadence through mid-2026. That said, the README documents no long-term support policy, no version compatibility matrix and no deprecation process. The upgrade command pulls new versions automatically, which means you are implicitly tracking the maintainers' release rhythm unless you find a way to pin.

The maintenance cost you are signing up for is concrete: two services to deploy if you use the sandbox, a stop-the-service backup routine, a two-step upgrade that updates the CLI before the application, and a host that meets the 4-core, 8GB floor. Verify first that Docker Compose V2 is what your host actually provides, since the README's verification command is docker compose version and not the older docker-compose binary. Then run one full backup and one full restore on a throwaway deployment before you put any real agent data in it.

Editorial conclusion

Adopt Nuwax if you need a self-hosted agent platform with a knowledge base, model proxy, memory and plugins, and you are willing to run Docker Compose on Ubuntu 22.04 or macOS. Do not adopt it if you need Windows support today, since the README lists Windows 10/11 as coming soon, or if you want a managed service with no host to operate. Before committing, verify three things on your own machine: that ./nuwax-cli docker-service status reports healthy after first start, that ./nuwax-cli auto-backup run completes and ./nuwax-cli list-backups shows the archive, and that your target server meets the stated 4 cores and 8GB RAM, because the sandbox service is documented as resource-hungry and intended for separate servers.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nuwax-ai/nuwax on GitHub
3. Project website
4. README
5. Releases