Skip to main content

How to Host an AI Agent on Your Own Server

Who This Is For​

This guide is for teams and companies that want to host an AI Agent on their own server, private network, or cloud account. It covers a complete self-hosted AI agent setup rather than only starting a binary.

xAgent is not a chat application installed on every personal computer. It runs on a server, while users access it through the web UI or IM connectors. Administrators prepare models, Skills, tools, external connections, and security policies first. Users then submit tasks, provide materials, and review results.

What Self-hosting Means for xAgent​

Self-hosting means that you decide where xAgent runs, where runtime data is stored, how users access it, and which external services it connects to. xAgent currently has no official SaaS release plan, so task files and workspace data do not need to be hosted on an official platform.

This does not mean all data automatically remains inside your environment. Model APIs, MCP services, connectors, and external business systems still process data according to their own integrations. Whether to use a local model, which external systems to allow, and who can access the service are deployment-owner decisions.

AI Agent Hosting Architecture​

CapabilityPractical meaning
No dependency on a personal computerTasks run on the server, so a submitted task can continue after a user shuts down their computer.
One access pointUsers can enter through the web UI or start and follow tasks from external entry points such as WeChat through IM connectors.
Centralized task filesMaterials, intermediate files, and results remain in server-side workspaces for continued work and later review.
User workspace isolationEach user accesses only their own workspace files, preventing task materials from different users being mixed together.
Task process isolationProcessSandbox mounts only authorized files and read-only Runtime Assets, then limits the process tree and resources.
Support for your own model serviceA local model or self-managed model gateway can keep task data in your own environment as much as possible.
Centralized governanceAdministrators configure models, Skills, tools, connectors, and approval policies once, then make them ready for users.

Self-Hosted AI Agent Setup Checklist​

A practical AI agent hosting setup must cover the runtime environment, model access, user entry points, security boundaries, and ongoing operations. Before the first deployment, clarify the following:

  1. Prepare an always-on Linux or macOS server. Windows is not recommended for deployment for now because its current sandbox support is not sufficient to provide safe and controllable execution of xAgent-managed scripts.
  2. Decide on a model source. You can connect a model API or run a local model service, but the model must support tool calling reliably.
  3. Plan the access path. Internal users can access the server directly; public or domain access should use Nginx, Caddy, or another reverse proxy for HTTPS.
  4. Define the first users and task scenarios. Start with low-risk work such as document organization, material analysis, or report generation.
  5. List external capabilities that are actually required. Add MCP services or connectors only when needed.

The current version uses embedded SQLite by default, so the first deployment does not require PostgreSQL, MySQL, or Redis.

1. Install and Start the Server​

Run the official installer. It detects the system and architecture, verifies release packages, and installs v0.0.5.beta. On Linux it configures and starts a systemd service; on macOS it installs under the current user.

2. Configure and Validate a Model​

Add at least one usable model in Model Configuration. Test normal chat, streaming, and tool calling first. At least 64k context is recommended; 100k or more is better for long tasks and complex scenarios. See Model Notes for details.

3. Complete Basic Security Setup​

Do not expose the xAgent port directly to the public internet. Use a reverse proxy for HTTPS, network controls, and firewall rules. Configure Approval Policies for sending messages, changing external data, and other sensitive actions when needed.

xAgent isolates user workspaces. Keys are also managed independently: tool configuration uses placeholders, and real values are substituted only when a tool call is made inside the system. Do not put passwords, tokens, or verification codes into session messages or task materials.

Confirm that ProcessSandbox and Runtime Assets are ready on the administrator Execution environment page. If the sandbox is unavailable, do not bypass the gate by running Tools directly on the host.

4. Validate with a Small Real Task​

Create an Agent Session, upload a small non-sensitive file, and complete a task with a clear, reviewable result. Confirm that model access, workspace read/write, file handling, and approvals work before opening the system to more users.

5. Add External Capabilities Only as Needed​

Use MCP when sessions need to call an external service on demand. Use Connectors when accounts, messages, or events from WeChat, email, or enterprise systems need to enter xAgent proactively. See What Is a Connector? for the difference.

Common Use Cases​

  • A team sends documents, spreadsheets, or source materials to an Agent and keeps results in server-side workspaces.
  • Users submit long tasks through the web UI and let the server continue after they leave their computers.
  • Users send a task from an authorized IM connector, while xAgent processes it and returns results from the server.
  • Administrators publish verified Skills and tools as shared capabilities so ordinary users do not need to configure them repeatedly.

Important Boundaries​

  • Self-hosted xAgent is not an offline desktop application. The server needs to stay online to receive and execute ongoing tasks.
  • A local model can improve data privacy, but MCP services, connectors, and external APIs still follow the data boundaries of the services you choose and authorize.
  • xAgent is currently beta. Before production use, validate models, external connections, approvals, and backups with real but non-sensitive tasks.
  • The installer supports pinned-version upgrades while preserving configuration and runtime data. If Linux activation fails, it attempts to restore the previous version. Back up first and verify the service, models, files, and Connectors after every upgrade.

Next Steps​

Last updated on