Docker

Docker Compose is the recommended way to run Xagent. The stack bundles the backend, frontend, database, sandbox, and reverse proxy.

Prerequisites

• Docker Engine 20+ and Docker Compose 2+
• At least 4 GB RAM and 20 GB disk on the host
• At least one model provider key or a reachable Xinference endpoint

Start the Stack

git clone https://github.com/xorbitsai/xagent.git
cd xagent
cp example.env .env
docker compose up -d

Then open the web app at http://localhost:80. On first run you are redirected to /setup to create the administrator account. The backend REST API is reached through the same port behind nginx (http://localhost:80/api/...) — the backend container does not publish port 8000; direct access at :8000 (with interactive docs at /docs) applies only when running the backend outside Docker via python -m xagent.web.

The SaaS Stack

To run the multi-tenant layer (teams, billing, the Workspace API), use the xagent-saas compose file, which wraps the core xagent service and adds the SaaS backend and frontend overlay:

cp .env.example .env   # add your Stripe keys
docker compose up -d

The SaaS stack's nginx binds to the loopback interface on port 8080 (http://127.0.0.1:8080) — front it with your own TLS-terminating proxy or load balancer for external access.

Reset the Admin Password

python -m xagent.web.reset_admin_password --username <admin_username>

Reverse Proxy

An nginx reverse proxy (nginx:latest, configured via docker/nginx.conf) routes traffic to the backend and frontend and can terminate TLS. Point your domain at the host and configure certificates (e.g. Let's Encrypt) for HTTPS in production.

Next Steps

• Environment Variables →