Self-Host Xyne Spaces and Access It with Localtonet

What Xyne Spaces is and what this guide deploys

Xyne Spaces describes itself as an organizational operating system built around a shared context layer. Connectors can bring information from organizational systems into a normalized store, while applications and agents use permission-aware APIs to retrieve the portion of that context available to the acting user. Its broader application set includes collaborative and organizational workflows such as Chat, Call, Canvas, Tickets, Customer Support Desk, Agentic Search, Automations, and Claw agents.

The project places access control at the data layer. Reads are scoped to the user, writes pass through a central permission layer, and agents inherit the permissions of the person invoking them. This matters when considering remote access. Making a web endpoint reachable does not replace application authorization, establish user permissions, or make every endpoint appropriate for public exposure. Network reachability and application authorization remain separate controls.

This article covers the development-oriented local quickstart documented by the Xyne Spaces repository. It does not describe a production deployment. The available project information establishes the required tooling, the startup command, and the local service addresses, but it does not establish a stable production release procedure or a complete production-hardening baseline. Treat the resulting installation as a local evaluation, development, or controlled testing environment unless the project publishes additional deployment guidance that fits your requirements.

Prepare the Xyne Spaces host

Choose a machine on which you can install development tools and run containers. The repository documents three principal software prerequisites: Node.js 22.x, pnpm 10.15.0, and Docker-compatible Compose. Git is also needed for the clone-based workflow described below.

Install each prerequisite using the supported method for your operating system. Package names and installation procedures differ among Windows, macOS, and Linux distributions, so this guide does not substitute an unverified platform-specific package command. The important point is to confirm the installed versions before starting the repository workflow.

Confirm the toolchain

Open a terminal and check that each command is available. These checks do not change your system or start Xyne Spaces:

node --version
pnpm --version
docker compose version
git --version

The Node.js result should identify a 22.x release, and the pnpm result should be 10.15.0. The Docker command should report a functioning Compose implementation. If your Docker-compatible environment exposes Compose differently, use its documented verification method rather than assuming that an unrelated command is equivalent.

Check local port availability

The documented local stack uses four HTTP endpoints: ports 5173, 3001, 3002, and 3003. Before starting, make sure another development server or container is not already occupying those ports. The exact port-inspection command depends on the operating system, so use your system’s network or process tools to identify listeners.

A collision can produce an obvious “address already in use” message, but it can also cause confusion if a browser reaches an unrelated service that was already listening. If a page appears on one of the expected addresses before Xyne Spaces starts, identify that process instead of assuming it belongs to this installation.

Plan where Localtonet will run

For the simplest remote-access arrangement, install the Localtonet client on the same machine as Xyne Spaces. The local Dashboard address uses localhost, which always refers to the machine making the connection. A Localtonet client running on a different device cannot interpret localhost:5173 as the Xyne Spaces host.

Our platform can target a service reachable from the client device, but using another device requires a valid LAN address and a service that accepts connections on that interface. The supplied Xyne Spaces quickstart evidence establishes the loopback URL, not a LAN binding procedure. This guide therefore uses the same-host arrangement and does not invent a bind-address change.

Install and start Xyne Spaces

The project’s documented quickstart is intentionally short. Keep the initial installation close to that workflow. Avoid making configuration changes before you know whether the unmodified stack starts successfully, because every early customization introduces another troubleshooting variable.

git clone https://github.com/juspay/xyne-spaces.git
cd xyne-spaces
pnpm run up

Watch the terminal output while the command runs. If it exits with an error, preserve the complete message, including the first meaningful error rather than only the final summary. Dependency failures, unavailable container services, port conflicts, and permission errors require different corrections.

The evidence available for this guide establishes pnpm run up as the startup command. It does not establish a matching shutdown, reset, upgrade, migration, or destructive cleanup command. We therefore do not provide guessed package scripts. Before stopping or resetting the environment, inspect the repository’s current scripts and documentation so that you use the operation supported by the revision you cloned.

Verify the local installation before publishing it

Remote access should be the final integration step, not a way to troubleshoot a service that has never worked locally. First verify the Dashboard from a browser on the Xyne Spaces host. Open:

http://localhost:5173

A successful result should be an application response from the Xyne Spaces Dashboard rather than a browser connection error. Complete any on-screen initialization that the current project version requires, but do not invent credentials or assume a default username and password. The supplied quickstart evidence does not establish default credentials.

Confirm that the response belongs to Xyne Spaces

Seeing any web page on port 5173 is not sufficient if another application was already running there. Check the page identity and compare it with the Xyne Spaces startup output. If you receive an unrelated application, stop and resolve the port collision. If you receive a generic proxy error, inspect the process and container state instead of proceeding to Localtonet.

Distinguish startup delay from a failed service

A multi-service development stack may not make every component ready at the same instant. If the browser initially fails while the terminal is still actively preparing the environment, wait for the startup process to settle and try again. If the terminal has stopped with an error, waiting will not correct the underlying problem.

Test with an explicit HTTP request when useful

A command-line request can help separate a browser-specific problem from basic HTTP reachability. If curl is available on the host, request the Dashboard address:

curl http://localhost:5173

An HTTP response indicates that something is listening, although the returned application may depend on browser-side JavaScript to render fully. “Connection refused” usually means no process is accepting a connection at that address. A response from the wrong application suggests a port collision. An application error response means the network path exists, but a component behind the page may still be unhealthy.

Understand the documented Xyne Spaces endpoints

The quickstart identifies four local HTTP endpoints. They belong to different parts of the stack and should not be treated as interchangeable public entry points. For ordinary browser access, the Dashboard on port 5173 is the natural target.

Publishing only the Dashboard follows a least-exposure approach. An internal API endpoint may lack the same navigation, browser workflow, or expected request path as the user-facing application. Directly exposing every port also increases the number of interfaces that must be reviewed, monitored, updated, and protected.

Xyne Spaces may make browser requests from the Dashboard to supporting services. Whether those requests flow through the Dashboard’s own origin, a development proxy, or direct local addresses depends on the current application configuration. The extracted quickstart does not establish a public multi-endpoint routing design. Verify the actual Dashboard workflow after tunneling rather than creating additional public tunnels speculatively.

Publish the Xyne Spaces Dashboard with Localtonet

Once the Dashboard works locally, we can make it reachable through a Localtonet HTTP tunnel. Our client establishes an outbound connection to a Localtonet relay server. This provides a public address without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

The tunnel points to the local Xyne Spaces Dashboard at IP address 127.0.0.1 and port 5173 when the Localtonet client runs on the same host. Creating the configuration is not enough by itself. The selected client device must be connected, and the tunnel must be started before the public address becomes available.

For the current product workflow and field names, consult our HTTP tunnel documentation. Dashboard options can evolve, so use the values presented in your account instead of copying an old relay code or domain configuration from another deployment.

Test from outside the host

Local verification proves that Xyne Spaces is responding, but it does not prove that the public route works. Open the assigned HTTPS URL from another device, an isolated browser profile, or a network that is not relying on the host’s loopback interface. Confirm that the page loads through the exact URL Localtonet assigned.

Then test more than the first page. Sign in only with an authorized account, navigate through the workflows relevant to the evaluation, and observe whether browser requests fail. A page shell can load even when a supporting request uses an unsuitable local-only URL. If that occurs, diagnose the failing request and consult the project’s current configuration guidance. Do not respond by publishing every supporting port.

Apply a safe remote-access model

A Localtonet tunnel solves network reachability. It does not convert a development installation into a hardened production service, create Xyne Spaces users, or replace the application’s permission model. Anyone who can reach a public URL can attempt to interact with the endpoint, so application authentication and authorization remain essential.

Review data before connecting organizational systems

Xyne Spaces is designed around organizational context and connectors. That context can include conversations, documents, tickets, email, calendars, transcripts, and other business records. Before importing real data, determine which users and agents can read it, where it is stored, how it is removed, and whether the development environment meets your organization’s policies.

The project describes agents as inheriting the invoking user’s access, with writes enforced through the permission layer. That application design is relevant, but it does not remove the need to verify current configuration and behavior in your own deployment. Test permissions with non-administrative accounts and synthetic data before relying on them for sensitive material.

Keep the agent boundary in view

Xyne Spaces describes agents that can run code, read repositories, execute shell commands, call internal APIs, and write files. The project also describes a separated architecture intended to keep untrusted runtime code away from credentials. Agent execution still deserves careful governance. Restrict connected systems, minimize credential scope, review write approvals, and avoid mounting unnecessary host paths or secrets into development components.

Update deliberately

A cloned development repository can change over time. Before pulling a new revision, review the project changelog, dependency changes, configuration requirements, and migration guidance. Preserve any important local data and configuration first. Re-run the local verification checks after updating, then test the public route. Do not assume that an existing tunnel proves a newly updated application is healthy.

Troubleshoot installation and remote-access problems

pnpm is not found or reports the wrong version

Confirm that pnpm is installed and available in the current terminal’s executable path. If the version is not 10.15.0, install or activate the documented version using the supported method for your operating system. Close and reopen the terminal if your installation tool changed environment variables.

Avoid deleting the project lockfile as an initial fix. A lockfile records the dependency resolution expected by the project, and replacing it may create a different dependency graph rather than correcting the local package-manager mismatch.

The container engine or Compose is unavailable

Run docker compose version and verify that the container engine itself is running. On systems using a desktop container application, opening a terminal does not necessarily start the engine. On service-based systems, check the service through the operating system’s normal administration tools.

If you use a Docker-compatible alternative, confirm that it supports the Compose behavior required by the repository. A command with a similar name does not guarantee compatibility with every Compose feature.

pnpm run up fails while building or starting services

Read upward from the final failure and find the first actionable error. Check the prerequisite versions, available disk space, container-engine status, network access needed to retrieve dependencies or images, and local port conflicts. Preserve the original output before retrying so repeated attempts do not hide the initial cause.

Do not compensate for a build failure by publishing a partially started port. The Dashboard may return incomplete content while a required API or storage service is unavailable. Resolve local startup first.

The Dashboard does not open on port 5173

Confirm that the startup command remains active and did not terminate. Verify that the browser address is exactly http://localhost:5173 when testing on the host. Check whether another process owns port 5173. If the client or browser runs in a virtual machine, container, or separate device, remember that its localhost is a different network namespace.

The local Dashboard works, but the public URL does not

Confirm that the Localtonet client is connected, the correct device token was selected, and the tunnel is actually running. Creating a tunnel does not start it. Verify that the local target is 127.0.0.1 with port 5173 when our client runs on the Xyne Spaces host.

If our client runs elsewhere, test whether that device can reach Xyne Spaces through a real LAN address. The quickstart only establishes a loopback endpoint, so a separate-host design may require application binding changes that are outside the evidence available for this guide.

The page loads remotely, but some actions fail

Use the browser’s developer tools to identify the failed request, its destination, and its HTTP status. A request aimed at localhost:3001, for example, refers to the remote user’s own machine when executed by that user’s browser. Do not automatically create a second public tunnel. First determine the routing configuration expected by the current Xyne Spaces revision.

Authentication failures should be investigated as application authorization issues, not tunnel failures. Server errors may indicate that a supporting service is unhealthy. Connection errors to a private address may indicate that the frontend generated a local-only URL.

The tunnel works only intermittently

Check whether the Localtonet client process remains running and whether the selected device stays connected. Also verify that pnpm run up and the required containers remain active. The public route depends on both layers: the local application must accept requests, and the Localtonet tunnel must be running through a connected client.

The wrong application appears at the public address

Test http://localhost:5173 again on the host. If that also shows the wrong application, another process owns the port. If local access is correct, verify the tunnel’s target IP and port and confirm that you are opening the address assigned to the intended tunnel.

Frequently asked questions