Xagent from Xorbits AI: a runtime for agentic work, not a flowchart builder

The problem Xagent targets: work that does not fit a pre-drawn flowchart

The README makes its position explicit: Xagent is not a static workflow builder, and it is not a chatbot wrapper. The argument is that knowledge work has moving requirements, incomplete inputs, and next steps that only become clear once a tool returns something. A workflow builder asks you to enumerate branches before the work starts. Xagent plans while the work happens.

That framing decides the audience. It suits people doing one-off research, writing, file handling and data exploration, where the value is in finishing the task rather than in reusing a diagram. It suits teams that repeat the same kind of operation and want to save it as a named agent with roles, tools, models and knowledge bases rather than re-prompting each time. It suits enterprises that need private models, private data and internal systems, which is why the repository carries Xinference integration and multi-user control in its feature list.

The README gives a concrete example of the intended shape of the work: a goal such as analyzing three competitors, summarizing positioning and drafting a launch plan is decomposed into a Planner Agent plus research, data, analyst, writer and operator agents. Whether that decomposition is always the right one is a separate question, but it shows what the project means by a workforce rather than a chain.

How the runtime is put together: FastAPI backend, Next.js frontend, Postgres and Redis

The repository layout is the clearest evidence of the architecture. src/ holds the Python package, frontend/ holds a Next.js application, docker/ holds the nginx configuration, and alembic.ini points at database migrations. The Compose file names three long-running services: nginx, frontend and backend.

The backend is FastAPI and uvicorn, and it is deliberately not published to the host. The Compose comment says it is only accessible through nginx, which proxies to the frontend and backend. State lives in Postgres through DATABASE_URL, and Redis appears twice: XAGENT_REDIS_URL for general use and XAGENT_CELERY_BROKER_URL on a separate database index for background jobs. Celery is enabled by default through XAGENT_CELERY_ENABLED, with XAGENT_BACKGROUND_JOB_VISIBILITY_TIMEOUT_SECONDS defaulting to 3600.

The Python dependency list shows what the agent loop is allowed to reach. LangChain and langchain-openai are present alongside the OpenAI, Anthropic, Google GenAI, ElevenLabs and zai SDKs, so model choice is a configuration concern rather than a code change. MCP is pinned below version 2 because, per the comment in pyproject.toml, streamablehttp_client in sessions.py was removed or renamed in mcp 2.0. asyncssh is listed as a production runtime dependency for the SSH MCP runner, not a test-only extra. Tracing goes through langfuse 4.x and the OpenTelemetry SDK with an OTLP HTTP exporter. Uploads are capped by XAGENT_MAX_UPLOAD_SIZE, defaulting to 100M, and artifact validation has its own byte and timeout limits.

Installing the Xagent CLI and running a first task

The README's local path needs Python 3.11 or newer and states that the published package bundles the web UI, so no Docker or Node is required. Install it as a tool and start it:

uv tool install xagent-ai   # or: pip install xagent-ai  (use a virtualenv)
xagent                      # then open http://127.0.0.1:8000

The README also offers a one-line installer:

curl -fsSL https://get.xagent.co | sh

After the server is up, open the address it prints, which the README gives as http://127.0.0.1:8000. The first visit redirects to /setup, where you create the admin account. The README says Xagent then guides you to the Models page to connect a provider, which is the step that makes the agent usable; nothing in the README suggests a model is configured for you.

If you are moving from OpenClaw or Hermes, the README documents a migration command that imports agents, skills and schedules:

xagent migrate --help

For a team or self-hosted setup, the README uses the repository's Compose file, which publishes nginx on port 80 by default:

git clone https://github.com/xorbitsai/xagent.git
cd xagent
cp example.env .env        # optional: review settings
docker compose up -d       # then open http://localhost:80

The Compose file shows the container images tagged 0.7.0 for both frontend and backend, with Postgres credentials derived from POSTGRES_PASSWORD and a default of xagent_password. Change that before the stack is reachable from anywhere but your own machine. If the admin password is lost, the README gives a reset command that runs inside the backend container:

docker compose exec backend python -m xagent.web.reset_admin_password --username <admin_username>

Browser sign-in depends on Web Locks, and the Compose endpoint is a development reference

This is the constraint most likely to surprise a team that deploys first and reads later. The README states that browser sign-in requires local browser storage and the Web Locks API for safe cross-tab session coordination. It then says the bundled HTTP Compose endpoint is a local-development reference, and that production deployments must terminate TLS and use a browser that supports Web Locks. localhost, 127.0.0.1 and ::1 remain secure-context forms for local development.

Read that as a boundary rather than a footnote. Putting the Compose stack on a plain HTTP hostname and expecting sign-in to work is not a supported path. You need TLS termination in front of it and a browser with Web Locks. The README points to docs/deployment.md for release-specific rollout and rollback requirements, which implies the upgrade path has its own procedure rather than being a simple image pull.

The licence is the second thing to check before adoption. pyproject.toml declares license as Xagent Source License, and the repository's licence identifier is NOASSERTION, meaning GitHub could not map the file to a known SPDX licence. The README does not reproduce the terms, so the only reliable source is the LICENSE file itself. Treat that as a task for whoever signs off on dependencies, not as a detail to resolve after the prototype works.

A third limitation is visible in the packaging metadata: the classifier reads Development Status :: 1 - Planning. The release cadence is real, with v0.7.4 dated 2026-09-13, v0.7.3 on 2026-09-05 and v0.7.2 on 2026-08-28, and the last push to the default branch was on 2026-09-17. Frequent releases on a 0.x line with a Planning classifier is a signal about interface stability, not about activity.

Xagent compared with a multi-agent framework you assemble yourself

The obvious alternative is a general multi-agent framework such as the LangChain and LangGraph stack, which Xagent already depends on. The difference is where the work sits. With a framework, you write the orchestration: you define the graph, the state object, the tool bindings and the retry behaviour, and you own the deployment. Xagent packages that orchestration behind a server with a web UI, an admin account, a models page, knowledge bases, publishing and a Compose file, and leaves the agent definition to configuration inside the product.

That trade is not automatically in Xagent's favour. A framework gives you a diffable, reviewable definition of the agent in your own repository. Xagent gives you a running system faster and a shared surface for a team, but the agent definitions live in the product's database rather than in your source tree, which matters if your change control expects pull requests for behaviour changes. The dependency list also shows Xagent pulling in the framework layer anyway, so you are not avoiding that stack; you are adopting it with a management layer on top.

A second comparison point is the workflow builder the README argues against. If your process genuinely is fixed and auditable, with branches you can enumerate and a compliance team that wants to read them, a static builder is the better tool and Xagent's runtime planning is a liability rather than a feature. Xagent is the wrong choice when the requirement is that the same input produces the same traceable path every time.

Upgrade cost, data you should expect to move, and licence handling

Upgrades are not a single command in the documentation. The Compose file pins image tags, currently 0.7.0 for both frontend and backend, while the releases run ahead of that at v0.7.4. Updating therefore means changing the tags you pull, and the README's pointer to docs/deployment.md for release-specific rollout and rollback requirements indicates the project expects you to read per-release notes rather than assume compatibility. The presence of alembic.ini means database migrations are part of the upgrade path, so a Postgres backup before pulling new images is the practical precaution.

On data, the Compose file mounts a named volume, xagent_data, into nginx at /root/.xagent read-only, and the backend writes uploads to /root/.xagent/uploads through XAGENT_UPLOADS_DIR. Your uploaded files and the database are the state you would need to carry across an upgrade or a move. Upload size is bounded by XAGENT_MAX_UPLOAD_SIZE, defaulting to 100M, and artifact validation is bounded by XAGENT_ARTIFACT_VALIDATION_MAX_BYTES at 32M and XAGENT_ARTIFACT_VALIDATION_TIMEOUT_SECONDS at 8, so very large artifacts are rejected by design rather than by accident.

On licensing, the honest statement is that the repository reports NOASSERTION and pyproject.toml names the Xagent Source License. Source-available licences vary widely in what they permit for hosted or commercial use, and the README here does not state the terms. Read LICENSE and have someone qualified decide whether your intended deployment fits. Nothing in this article should be read as a legal opinion.

What to verify before you commit a team to Xagent

Verify the licence text against your intended use, because NOASSERTION tells you only that GitHub could not classify it. Verify that your production hostname serves HTTPS, since the README ties browser sign-in to a secure context and the Web Locks API. Verify that the browser your team actually uses supports Web Locks, because a failure there looks like a login bug rather than a compatibility issue.

Verify the model path. The README says the Models page is where you connect a provider, and the dependency list includes OpenAI, Anthropic, Google GenAI, ElevenLabs and Xinference clients, but the README does not say which provider is configured by default, so assume none is. Verify that your Postgres password is not the default xagent_password from the Compose file before the stack is reachable.

Finally, verify the upgrade procedure from docs/deployment.md rather than from the README, because the README explicitly defers rollout and rollback requirements to that document. If your team cannot accept a 0.x release line with a Planning classifier, the honest answer is to wait for the versioning to settle or to build on the underlying framework directly.

Editorial conclusion

Adopt Xagent if you want a single installable runtime that covers a personal agent, a published team agent and a self-hosted deployment, and you are willing to read the licence before shipping it. Do not adopt it if you need a fixed, auditable flowchart of every branch, or if the NOASSERTION licence identifier on the repository has not been resolved by your legal review. Verify three things first: the exact terms in LICENSE, that your browser supports the Web Locks API if you sign in through a browser, and whether the Docker Compose endpoint is acceptable for anything beyond local development.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. xorbitsai/xagent on GitHub