Build a team knowledge workspace locally, verify it, then provide controlled remote access
Yuxi is a self-hosted, multi-user knowledge-agent platform that combines document ingestion, RAG, knowledge graphs, agent workflows, tools, and permission management. In this guide, we install Yuxi with Docker Compose, check its backend readiness, complete the first browser login, and outline a practical knowledge-base validation workflow. Once the local deployment works correctly, we connect its web frontend to an HTTP tunnel with Localtonet so authorized remote team members can reach it without inbound router port forwarding, firewall changes, a VPN, or a public IP address.
📋 What's in this guide
What this deployment includes
Yuxi is more than a single document-search container. Its documented Docker deployment brings together a Vue web interface, a FastAPI backend, LangGraph-based agent execution, PostgreSQL, Milvus, Neo4j, document-processing components, and supporting workers. The resulting platform is intended for multi-user, self-hosted knowledge and agent workflows.
A team can use Yuxi to collect documents into knowledge bases, parse and divide those documents into chunks, build vector indexes, test retrieval, apply reranking, and supply retrieved material to an agent. Its documented capabilities also include knowledge-graph construction, configurable agents, subagents, Skills, MCP integrations, sandboxed workspaces, generated files, user and department permissions, model configuration, and operational dashboards.
This guide deliberately divides the deployment into two phases. The first phase installs and verifies Yuxi entirely on the host. The second phase adds remote access with Localtonet. Keeping those phases separate makes troubleshooting much easier. If the service does not work on localhost, adding a public URL will not repair the underlying application.
Which endpoint should remote users access?
The documented browser frontend is available locally at http://localhost:5173. The FastAPI backend is available separately on port 5050, with interactive API documentation at http://localhost:5050/docs and a readiness endpoint at http://localhost:5050/api/system/ready.
For an ordinary remote-team deployment, the frontend on port 5173 is the primary endpoint to expose. The backend documentation and readiness URL are useful for local administration and diagnostics, but they do not normally need separate public tunnels merely to let users work in the web application. Avoid increasing the public attack surface without a specific operational reason.
Localtonet carries traffic to a service that is already running. Yuxi remains responsible for application login, users, permissions, model configuration, knowledge access, and agent behavior. Confirm all of those controls locally before inviting remote users.
Prerequisites for a Yuxi installation
Prepare the host before cloning the repository. The documented quick start requires Docker Engine, Docker Compose, Git, and access to a usable large-model API. Docker must have permission to create containers, networks, volumes, and images for the complete stack.
| Requirement | Why it is needed | How to check it |
|---|---|---|
| Docker Engine | Runs Yuxi and its supporting services in containers. | Confirm that docker version can contact the Docker engine. |
| Docker Compose | Builds and manages the multi-container topology defined by the repository. | Confirm that docker compose version returns a version. |
| Git | Clones a specific Yuxi release tag from the official repository. | Confirm that git --version succeeds. |
| Model API access | Yuxi needs model access for its AI and knowledge workflows. | Have the appropriate provider credential available during initialization and configuration. |
| Local browser access | Completes the initial administrator setup and verifies the frontend. | Use a browser on the host or from an appropriately trusted local network path. |
| Localtonet client | Creates the outbound connection used for remote access after Yuxi works locally. | Install the current client on the Yuxi host or another device that can reach it. |
The official evidence supplied for this guide does not establish a universal minimum CPU count, memory allocation, disk capacity, or supported operating-system matrix. The stack includes databases, vector search, graph storage, document processing, API services, and workers, so resource demand will vary significantly with document volume, parsing workload, concurrent users, model choices, and enabled features. We therefore do not invent a minimum specification.
Before using real team data, make sure the selected host has persistent storage and enough headroom for container builds, database files, uploaded documents, indexes, generated artifacts, logs, and backups. A successful container start on a lightly loaded test host is not by itself proof that the same host is sized for production.
Network and credential preparation
The host needs outbound connectivity for cloning the repository, obtaining container images or build dependencies, contacting the configured model provider, and establishing the Localtonet relay connection. An inbound public port is not required for the Localtonet workflow because our client establishes an outbound connection to a relay server.
Treat model credentials, generated JWT secrets, API-key derivation secrets, sandbox secrets, Yuxi administrator credentials, and the Localtonet device token as sensitive. Do not commit them to source control, paste them into tickets, include them in screenshots, or place them in this article's example commands.
Choose and verify one Yuxi version
Version consistency deserves special attention. The supplied release evidence identifies v0.7.2 as a published release, while the current quick-start text targets v0.7.3 and says that the repository's default configuration corresponds to that version. A deployment guide should not silently clone one release while applying initialization, Compose, migration, or configuration instructions written for another.
Before running the commands below, check the official Yuxi repository and release list and confirm that the tag named by the current quick start actually exists. If v0.7.3 is available and remains the version documented by the project, use that tag consistently. If it is not available, use a confirmed published tag and follow the documentation shipped with that exact checkout rather than mixing commands across versions.
The commands in the installation section follow the current quick-start text for v0.7.3. Verify that this tag exists before cloning it. If your organization selects v0.7.2 instead, use the files and upgrade guidance contained in the v0.7.2 checkout. Do not assume that database layouts, environment templates, migration steps, or Compose behavior are interchangeable.
Pinning a release tag also makes the deployment reproducible. A shallow clone of a named tag avoids accidentally installing whatever happens to be on the moving default branch. Record the selected tag, the date of installation, local configuration changes, model providers, backup procedure, and any enabled Compose profiles in your internal runbook.
Install and start Yuxi with Docker Compose
The documented installation sequence is to clone the selected release, enter the repository, run the supplied initialization script, and then build and start the Compose stack. Run these commands from a trusted administrative session on the host.
Clone the verified release and enter the repository
After confirming that the quick-start tag exists, clone that exact tag with a shallow history. The following command uses the version named by the current Yuxi quick start.
git clone --branch v0.7.3 --depth 1 https://github.com/xerrors/Yuxi.git
cd YuxiIf you deliberately choose another release, replace the tag only after reviewing the documentation from that release. Do not run the rest of this workflow against an unverified tag.
Run the Yuxi initialization script
On Linux or macOS, run the repository's initialization script:
./scripts/init.shOn Windows PowerShell, the documented counterpart is:
.\scripts\init.ps1
The initialization process creates the local .env file, reads the model API credential requested by the current setup, and generates separate secrets for JWT handling, API-key derivation, and the sandbox provisioner. The current quick-start description specifically mentions reading a SiliconFlow API key. Follow the prompt presented by the selected release rather than placing a real key directly in command history.
Yuxi also documents manual initialization by copying .env.template to .env and filling the required values. Use that path only when you understand every required setting and can generate appropriate independent secrets. Do not reuse one password-like value for all secret fields.
Build and start the development stack
From the repository root, use the documented Compose command:
docker compose up --build -d
The --build option builds the required application images, while -d starts the stack in detached mode. Initial startup can take longer than later restarts because images and dependencies may need to be built or retrieved.
The .env file can contain provider credentials and security-sensitive values. Restrict access to the deployment account and administrators who need it. Never publish this file, include it in a support transcript, or commit it to a Git repository.
What the initialization step accomplishes
Initialization is not merely a convenience wrapper around Compose. It prepares local configuration and generates multiple security values that different Yuxi components use. Running the official script helps prevent missing variables and discourages insecure reuse of a single hand-written secret across unrelated functions.
If the script fails, stop and correct that failure before starting the stack. Common categories to inspect include script execution permissions, the current working directory, shell compatibility, write permission for the repository, and whether the requested model credential was supplied. The available evidence does not define every script error message, so use the actual terminal output and the documentation shipped with your selected release rather than guessing a variable name.
Verify Yuxi before enabling remote access
Verification should proceed from the container layer to the backend and finally to the browser. This order distinguishes infrastructure failures from API startup problems and frontend access problems.
Inspect the Compose service state
From the Yuxi repository directory, list the services managed by the current Compose project:
docker compose psReview the actual output for stopped, restarting, unhealthy, or missing services. Do not continue merely because one frontend container appears to be running. Yuxi depends on several application and data services.
Check the backend readiness endpoint
Run the documented readiness request on the host:
curl --fail http://localhost:5050/api/system/ready
Wait until the returned status is ready. The --fail option makes HTTP error responses fail the command, which is more useful for scripts and deployment checks than treating every response as success.
Open the local web interface
Visit http://localhost:5173 in a browser. Follow the on-screen process to initialize the super administrator, then log in. Use a strong, unique administrator password and store it according to your organization's credential policy.
Inspect the API documentation only if needed
The FastAPI documentation is available locally at http://localhost:5050/docs. It is useful when developing an integration or diagnosing backend behavior. Normal browser users should use the frontend rather than the API documentation interface.
A proper local acceptance check should include more than loading the sign-in screen. Confirm that the administrator can authenticate, the primary interface renders without repeated browser errors, and the application can reach its configured model service. Then test the actual knowledge workflow described in the next section.
localhost refers to the machine making the request. A browser running directly on the Yuxi host can use http://localhost:5173. A Localtonet client on another device cannot use its own localhost to reach Yuxi. In that arrangement, the tunnel target must be an address through which the client device can reach the Yuxi host.
Create and validate a private RAG workflow
Once the platform is healthy, test the feature the deployment is intended to provide. Yuxi's knowledge workflow covers document upload, parsing, chunking, vector indexing, retrieval tests, reranking, agent use, and evaluation. The exact labels and available settings can differ by release, so use the interface presented by your verified checkout rather than relying on assumed menu names.
Start with a controlled document set
Create a small pilot knowledge base using documents whose contents and expected answers are already known to the deployment team. Yuxi documents support for common formats including PDF, Word, PowerPoint, Excel, Markdown, and other text-oriented material. A controlled pilot makes it possible to distinguish a retrieval problem from a vague or contradictory source-document problem.
Do not begin by importing every internal file. Start with a narrow collection, verify permissions, observe parsing behavior, and confirm that the selected model and retrieval configuration produce useful results. This approach limits accidental exposure and provides a baseline before adding more departments or data types.
Wait for parsing and indexing
Uploaded files must be processed before retrieval can work reliably. Yuxi provides document parsing, chunk generation, token information, and vector indexing. Depending on the content, parsing can involve text, images, tables, OCR, and document-specific engines. Large files and image-heavy documents may take longer than simple Markdown or text files.
Review the status presented by the interface and investigate failed files rather than assuming an upload guarantees searchable content. For a test document, inspect the resulting chunks if that capability is available in the selected release. Confirm that headings, tables, and key statements were extracted in a form that can support retrieval.
Test retrieval before testing an agent answer
A generated answer can sound convincing even when the correct source passage was never retrieved. Use Yuxi's retrieval-testing workflow to submit questions with known source passages. Compare the initial embedding or hybrid retrieval results with reranked results where configured. Check whether the expected chunk appears and whether irrelevant chunks dominate the ranking.
If retrieval is weak, adjust the knowledge configuration and source material before changing an agent prompt. Useful diagnostic questions include whether the relevant file finished parsing, whether the expected text exists in a chunk, whether the query uses terminology found in the documents, and whether the configured embedding and reranking models are operational.
Attach knowledge to the intended agent
Yuxi agents can combine model configuration, prompts, knowledge bases, tools, Skills, MCP services, and subagents. Attach only the knowledge and capabilities required for the agent's role. A general team assistant does not automatically need access to every department's documents or every external tool.
Test several questions that cover exact facts, paraphrased facts, unsupported questions, and potentially conflicting source documents. A useful private RAG deployment should retrieve relevant material when it exists and avoid presenting unsupported statements as established knowledge when it does not.
Validate permissions with a non-administrator account
Administrator success does not prove that team access is correctly configured. Create representative user or department access according to Yuxi's permission model, then test what an ordinary account can view and modify. Confirm access to the intended knowledge bases, agents, Skills, model capabilities, and workspaces while checking that unrelated resources remain unavailable.
Repeat this test after any major permission change. Remote connectivity should not be confused with application authorization. A user who can reach the public URL still needs an appropriate Yuxi account and only the permissions required for their work.
Publish the verified Yuxi frontend with Localtonet
After http://localhost:5173 works on the Yuxi host, add remote access as a separate layer. With Localtonet, our client establishes an outbound connection to a relay server. The resulting HTTP tunnel provides a public HTTPS address without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Run the Localtonet client on the Yuxi host when possible. This allows the tunnel target to remain localhost. You may instead run our client on another trusted device that can reach Yuxi over the local network, but in that design the target must be Yuxi's reachable local address rather than the client device's loopback address.
Install and run the Localtonet client
Install the current Localtonet application on the Yuxi host or on another device that can reach the Yuxi frontend. Use the current installation method for that operating system. We do not include an unverified client command here because installation commands can vary by platform and client version.
Authenticate or select the client device
Use the device-specific authentication token associated with the client that will run the tunnel. Keep this token private. Do not paste it into documentation, screenshots, chat messages, or shell examples.
Select an available relay server
Choose a currently available server or region from the Localtonet dashboard. Available server codes and regions can change, so obtain the value from the current product interface rather than copying a hardcoded example.
Create an HTTP tunnel for the Yuxi frontend
Select an HTTP tunnel and point it to the Yuxi frontend. If our client runs on the same host, use local IP 127.0.0.1 with port 5173. If the client runs elsewhere, use the Yuxi host address that is reachable from the client device and confirm local network policy permits that connection.
HTTP tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain. Current availability can vary. If you use a custom domain, follow the current Localtonet DNS instructions rather than guessing records from an older example.
Start the tunnel
Creating the tunnel does not make it active. Press the Start button and wait until the selected client is connected and the tunnel is running. Copy the assigned public HTTPS URL only after the active state is confirmed.
Test from an external connection
Open the assigned URL from a device that is not relying on the Yuxi host's local network path, such as an authorized test device on a separate connection. Confirm that the Yuxi login page loads, authentication succeeds, and an approved user can complete a representative knowledge query.
The tunnel remains available only while the selected Localtonet client is connected and the tunnel is running. Stopping the client, disconnecting the host, or stopping the tunnel removes the remote path. Stop or delete the tunnel when it is no longer needed.
We document current HTTP tunnel concepts and workflows in our Localtonet HTTP tunnel documentation. Use the current dashboard and documentation for client-version-specific fields and custom-domain requirements.
| Endpoint | Local purpose | Recommended exposure |
|---|---|---|
http://localhost:5173 |
Yuxi browser frontend for users and administrators. | Primary target for the Localtonet HTTP tunnel. |
http://localhost:5050/api/system/ready |
Backend readiness verification and operational checks. | Keep local unless a specific secured monitoring design requires remote access. |
http://localhost:5050/docs |
Interactive FastAPI documentation for development and diagnostics. | Do not expose by default for ordinary remote users. |
Security guidance for remote team access
Self-hosting controls where the application runs, but it does not automatically make every deployment private or secure. A public tunnel makes the selected web endpoint reachable from the internet. Treat that change as a production access decision even if the host is a workstation or lab server.
A hard-to-guess public URL is not a substitute for authentication and authorization. Complete Yuxi's administrator setup, create individual user accounts, apply least-privilege permissions, and test access boundaries before distributing the URL.
Use individual identities and least privilege
Avoid shared administrator accounts. Give each user the access required for their role and no more. Separate administration, knowledge curation, agent configuration, and ordinary query access where the platform's permission model supports that distinction. Review department and shared-resource permissions before adding sensitive documents.
Limit exposed services
Expose the frontend required by users, not every local port in the stack. PostgreSQL, Milvus, Neo4j, internal workers, sandbox services, the readiness endpoint, and interactive API documentation should not receive public tunnels merely because they exist. Each extra endpoint creates another access path to maintain, monitor, and secure.
Protect provider keys and generated secrets
Model provider credentials and generated application secrets should remain on the host and outside source control. Restrict filesystem access to .env, deployment backups, and persistent volume data. Yuxi's documented model management can centralize provider credentials and keep keys hidden from ordinary members, but administrators must still protect the underlying configuration and host.
Control document ingestion
Before uploading company material, classify it and confirm who should be allowed to retrieve it. RAG systems can surface small passages from a large document in contexts users may not anticipate. Validate knowledge-base sharing, agent attachments, department permissions, generated artifacts, and sandbox file access with representative non-administrator accounts.
Preserve application-level approvals
Yuxi includes agent execution, tools, subagents, Skills, MCP integration, sandbox workspaces, and human approval concepts. Review powerful capabilities separately from basic question answering. An account that only needs document retrieval may not need file modification, external tools, remote integrations, or broad sandbox permissions.
Plan backup and recovery before production use
The application state is distributed across databases, object or file storage, indexes, uploaded documents, configuration, and generated workspace data. A source-code clone is not a backup of that state. Define a version-specific backup and restoration procedure, secure the backup media, and test restoration before treating the service as a durable team system.
Exact production backup commands are not included here because they depend on the selected Yuxi release, Compose file, environment, profiles, and storage arrangement. Use the production guidance shipped with the deployed release, and preserve the complete set of components that must be restored to the same point in time.
Routine operations, upgrades, and troubleshooting
Check service state and logs
Start diagnosis with the same layers used during installation. Run docker compose ps from the correct repository directory, check readiness, and test the local frontend before investigating the public URL. For a service that is stopped or repeatedly restarting, inspect its Compose-managed logs:
docker compose logs SERVICE_NAME
Replace SERVICE_NAME with a service name shown by docker compose ps. This placeholder is intentional because service names can differ by release. Avoid copying guessed container names from unrelated installations.
Restart the current stack carefully
When a simple restart is appropriate and no migration is involved, operate from the same checkout and with the same environment and Compose parameters used for the deployment. Do not switch tags or edit persistent-volume settings as part of an improvised restart.
docker compose down
docker compose up -dA restart does not solve an invalid configuration, unavailable model provider, failed database migration, full disk, or corrupted persistent state. Review service logs and readiness output when the problem returns.
Do not treat an upgrade as a restart
Yuxi explicitly warns that upgrades from v0.7.1 or v0.7.2 to the current documented version must not be performed by simply running docker compose up. Those versions include changes involving database and persistent file layouts.
The published v0.7.2 release notes also describe a controlled migration from v0.7.1: schedule downtime, stop API and worker writes, make a coordinated backup of PostgreSQL, MinIO, and Yuxi file volumes, and run the release-specific storage migration with the same Compose, environment-file, and profile parameters intended for the final restart. Historical SQLite LangGraph checkpoints are not migrated, and some historical knowledge-base assets require special handling.
Before changing a production deployment, review the migration guidance from the currently installed release to the exact target release. Back up all required state at one consistent downtime point and verify that it can be restored. Never infer a migration path from the fresh-install commands in this guide.
Frontend does not load locally
Confirm that the browser is opening http://localhost:5173 on the host where Yuxi is running. Check docker compose ps, then inspect logs for services that are stopped, unhealthy, or restarting. Also confirm that the Compose command was run from the intended checkout and that initialization completed before the build.
Readiness never becomes ready
A frontend container can exist while a backend dependency remains unavailable. Inspect all Compose services, not just the API. Look for authentication failures, unavailable data services, initialization errors, disk exhaustion, model configuration problems, or a failed build. Use the exact errors in the logs and the documentation for the selected release.
The frontend works locally but not through Localtonet
First confirm that the local target still responds from the device running our client. If the client and Yuxi run on the same host, test http://127.0.0.1:5173 there. If they run on separate devices, test the Yuxi host's reachable local address from the client device.
Then confirm that the correct Localtonet device is connected, the HTTP tunnel points to the expected target and port, the selected relay server is available, and the tunnel has been started. Remember that creating a tunnel is not the same as starting it.
The public page opens but login or application actions fail
Retest the same operation locally. If it fails locally, investigate Yuxi and its dependencies. If it succeeds locally but fails only through the public URL, collect the browser error, application logs, and exact failing operation. Avoid publishing logs before removing credentials, tokens, private URLs, document content, and user information.
Retrieval returns irrelevant passages
Verify that the correct document was uploaded, parsing finished, expected content appears in generated chunks, and the intended knowledge base is attached to the agent. Use retrieval testing before evaluating final answers. Compare results with and without reranking where configured, and use questions with known expected passages.
Remote access stops unexpectedly
Check whether the Yuxi host is online, whether the Localtonet client is running and connected, and whether the tunnel remains started. The public address is available only while the selected client and tunnel are active. Also verify that Yuxi still responds locally, since a healthy tunnel cannot compensate for a stopped frontend.
Frequently asked questions
Which Yuxi port should I expose with Localtonet?
For normal browser access, target the Yuxi frontend on port 5173. The backend on port 5050 provides API documentation and readiness functionality, but it usually does not need a separate public tunnel for ordinary users.
Does Localtonet require router port forwarding or a public IP address?
No. Our client creates an outbound connection to a Localtonet relay server. This allows the tunnel to provide a public URL without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Should the Localtonet client run on the same host as Yuxi?
Running it on the same host is the simplest arrangement because the tunnel can target 127.0.0.1:5173. A different device can run the client if it can reach Yuxi over the local network, but the target must then be Yuxi's reachable address rather than the client device's localhost.
Is the Yuxi service private after I create a public tunnel?
The application remains self-hosted, but the selected endpoint becomes reachable through its public URL while the tunnel is active. Use Yuxi authentication, individual accounts, least-privilege permissions, and appropriate operational controls. Do not treat an unshared or unpredictable URL as an authorization mechanism.
Can I expose the Yuxi API documentation too?
It is technically a local HTTP endpoint, but ordinary team access does not require a separate public tunnel to http://localhost:5050/docs. Keep it local unless you have a specific integration requirement and have designed appropriate authentication, authorization, and monitoring for that additional exposure.
Which Yuxi version should I install?
Use a confirmed published tag that matches the documentation you are following. The current quick-start evidence names v0.7.3, while the supplied release evidence identifies v0.7.2. Verify the current release list before cloning, then keep the code, environment template, Compose files, initialization instructions, and migration guidance on the same version.
Can I upgrade Yuxi by pulling new code and running Docker Compose again?
Do not assume that is safe. Yuxi's documented upgrades from earlier releases can include database and persistent-storage migrations. Use the production upgrade guide for the exact source and target versions, schedule downtime where required, create coordinated backups, and follow the documented migration sequence.
Why does Yuxi need a model API during setup?
Yuxi's agent and knowledge workflows depend on configured model capabilities. The documented prerequisites require an available large-model API, and the current initialization description mentions reading a SiliconFlow API key. Follow the prompts and model-configuration guidance included with your selected release, and keep provider credentials secret.
Does a successful readiness check prove that RAG is working?
No. Readiness establishes that the backend reports itself ready. You should still sign in, upload a controlled document set, wait for parsing and indexing, test retrieval with known questions, attach the intended knowledge base to an agent, and verify permissions with a non-administrator account.
Connect your verified Yuxi workspace with Localtonet
Install Yuxi, confirm the frontend and RAG workflow locally, then create an HTTP tunnel to port 5173 for authorized remote team access without inbound router port forwarding.
Get Started Free →
