# matrix.to: Private Matrix Links and Local Setup > matrix.to turns Matrix room, user, and message identifiers into app-neutral links while calculating redirects in the browser. It suits publishers and communities that want shareable Matrix destinations, but its landing-page previews can still expose IP addresses to remote homeservers. **matrix-org/matrix.to** — A simple stateless privacy-protecting URL redirecting service for Matrix - Repository: https://github.com/matrix-org/matrix.to - Website: http://matrix.to - Stars: 1,423 · Forks: 317 - Language: JavaScript - License: Apache-2.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/matrix-org-matrix-to ## Why matrix.to Matters for Matrix Communities matrix.to addresses a distribution problem in the Matrix ecosystem. A room, user, or message has a Matrix identifier, but a link intended for the public often needs to tell web clients what to do with that identifier. matrix.to provides a stable web address for these entities without tying the shared link to one application. The README describes it as both a URL redirection service and a landing page for rooms and communities. Publishers putting chat links on websites are the clearest intended users. Community members are another audience, especially when sharing destinations through channels that may not have native Matrix handling. The project also supplies an SVG badge, which makes a link easier to place in a README or website. The badge does not carry the destination itself. It accompanies a matrix.to URL, so its use does not remove the question of which destination and client configuration appear in that link. This is a small utility with a narrow purpose. It does not replace a homeserver, room membership system, moderation service, or Matrix client. Instead, it translates a human-facing link into a client selection or Matrix destination. That scope also defines its privacy claim. The redirect calculation is local, but preview loading can cause network requests to the homeservers associated with the linked entity. ## How matrix.to Keeps Identifiers Out of Requests The central design choice is the URL fragment. A conventional path such as `/room/example` is normally available to the web server and can appear in HTTP requests. matrix.to puts the target details after a fragment beginning with the mandatory `#/` component. Browsers do not send the fragment to the server in an HTTP request. According to the README, the redirection is calculated entirely client-side with JavaScript, so the matrix.to server does not receive the link details used for that calculation. The documented URL forms cover four entity types. A room alias uses a `#` form, a room ID uses a `!` form, a user uses an `@`, and a message appends a message reference to a room URL. Spaces do not have a separate entity type because the README says they are technically rooms. The service can also pass optional client or web-instance hints, such as `client=element.io`, `web-instance[element.io]=chat.mozilla.org`, or `via=mozilla.org`. The README points to trusted web instances in `src/open/clients/Element.js`. That is a concrete file for operators to inspect when deciding which web clients should be suggested. It does not document a broader trust policy or guarantee that every external client behaves identically. The fragment protects the target from the matrix.to host, not from every service involved after the browser starts opening or previewing the destination. ## Running matrix.to Locally The repository documents a local development path for people who want to inspect the application or host their own version. `package.json` identifies the project as an ES module and requires Node.js `>= 14.0.0`. Its scripts include `start` and `build`; the README's setup uses `yarn start`, which invokes `node scripts/serve-local.js`. Install Yarn first using the link in the README, then clone the repository and install its locked dependencies. These commands reproduce the documented build instructions. The reader should expect the local server to listen on port `5000`, because the README directs the browser to `http://localhost:5000`. ```bash git clone https://github.com/matrix-org/matrix.to cd matrix.to yarn yarn start ``` After the server is running, open the local URL in a browser. A practical first check is to paste a documented room link into the address bar and inspect the page. The README gives this example, which targets the Matrix community room: ```text https://matrix.to/#/#matrix.to:matrix.org ``` The local URL will be `http://localhost:5000` when following the README's setup steps. This verifies that the JavaScript application is being served and that the browser can process a fragment-based link. It does not verify that the target room is reachable, that the selected client is installed, or that room membership rules permit the current account to join. The README says links to rooms by ID should only be used for rooms to which the target user has been invited, because such links cannot be assumed to work for every visitor. ## Badges and Client Parameters for Published Links The README provides two badge forms. The Markdown form places the badge image inside a link to a matrix.to room. The HTML form adds `rel="noopener"` and `target="_blank"`, while the image's `alt` text reads `Chat on Matrix`. These are useful starting points for a website, but the destination should be selected by the publisher rather than copied blindly from an example. ```md [![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#matrix.to:matrix.org) ``` The HTML version is: ```html Chat on Matrix ``` Optional parameters can steer the browser toward a particular client or web instance. The README names `client=im.fluffychat`, `client=element.io`, `web-instance[element.io]=chat.mozilla.org`, and `via=mozilla.org`. These parameters are configuration hints, not evidence that the named client is available, correctly configured, or acceptable for every visitor. The documentation does not describe fallback behavior when a named client is missing. ## Preview Privacy and Failure Boundaries The privacy model has a clear boundary. The README says matrix.to does not share followed-link information with its own server because the redirect is calculated in JavaScript and the details are hidden behind a fragment. It also acknowledges that the landing page can leak the visitor's IP address to homeservers involved with the linked entity while previews are fetched. An opt-out is available when no previews should be loaded. That setting matters for visitors who do not want the landing page to contact Matrix homeservers. The service is not a single point of failure in the sense described by the README. If the deployment becomes unavailable, users can copy room, user, or message details from URLs and follow them manually, or change the hostname to another deployment. The README also mentions hosting the application in an immutable or signed environment such as IPFS to improve availability and reduce tampering. These are availability properties, not a documented guarantee about preview privacy, operator security, or client compatibility. Identity and access remain separate concerns. A room alias, room ID, user identifier, and message URL identify different kinds of Matrix destinations. The README specifically warns that room-ID links are appropriate only for invited users. The service cannot make an inaccessible room accessible, and the documentation does not promise a stable account identity or permission model. ## Self-Hosting Versus Manual Matrix Links A practical alternative to relying on the public deployment is running another matrix.to instance. The README explicitly invites self-hosting and says users can change the hostname to point at an alternative deployment. This keeps the fragment-based link format and client-side calculation while changing the origin that serves the landing page. The trade-off is operational. A self-hosting party becomes responsible for serving the repository application, keeping its files available, and deciding how visitors reach the deployment. The repository includes `scripts/build.js`, and `package.json` defines a `build` script, but the README does not provide production deployment instructions or an operator release process. The other alternative is manual use of Matrix identifiers. The README says a user can copy room, user, or message details from a matrix.to URL and follow them manually if the service fails. Manual use avoids dependence on the redirector, but it removes the shared landing page, badge, client hints, and preview workflow associated with the link. IPFS is also mentioned as a possible hosting environment. The README presents this as an immutable or signed deployment option. It does not explain the operational steps, persistence guarantees, or compatibility details of that setup, so it should be treated as a hosting idea rather than a complete deployment guide. ## Maintenance and Apache-2.0 Upgrade Surface The repository is not archived, and its last push was on 2026-08-25. The latest listed release is `1.2.17`, dated 2024-09-02. These facts show a recent repository change alongside an older listed release, but they do not establish a future release cadence or a support policy. The project is licensed under Apache-2.0, as stated in `package.json`, and the repository contains a `LICENSE` file. Reviewing that file is the relevant step when determining obligations for redistribution or modification. This article does not provide legal advice, and the repository does not document compatibility guarantees for particular Matrix clients. The upgrade surface is visible in `package.json` and `yarn.lock`. The package declares build and start commands and development dependencies for Babel, Rollup, PostCSS, static serving, and related tooling. The lockfile belongs in the install review because the README uses `yarn` after cloning. Maintainers should check `package.json`, `yarn.lock`, and the scripts together when reviewing an upgrade rather than treating the hosted URL as an independently versioned client. ## Conclusion Publishers and Matrix communities should adopt matrix.to when app-neutral links and browser-side routing fit their needs, while privacy-sensitive organizations should first inspect preview opt-out behavior and hosted deployment policy. Do not adopt it as a durable Matrix identifier system without confirming that visitors can recover or redirect links through another deployment. For self-hosting, verify Node.js 14 or newer, room preview behavior, trusted web instances, and the operational cost of serving the JavaScript application. ## FAQ ### How do I install and run matrix.to locally? Install Yarn, clone the repository, run `yarn` in the project directory, and run `yarn start`. The README then directs you to `http://localhost:5000`. ### What does matrix.to do with a room or user link? The link details are placed behind a URL fragment and calculated client-side with JavaScript. The README says this prevents the matrix.to server from receiving the followed link details. ### Does matrix.to protect my IP address when previews are loaded? Not completely. The README says the landing page may leak a visitor's IP address to homeservers involved with the linked entity while fetching previews, and documents an opt-out for disabling previews. ### Can I use a matrix.to link for any Matrix room? Links to rooms by ID should be used only for rooms to which the target user has been invited, according to the README. The documentation does not assume that such links work for all visitors. ## Sources - [License: Apache-2.0](https://github.com/matrix-org/matrix.to/blob/main/LICENSE) - [matrix-org/matrix.to on GitHub](https://github.com/matrix-org/matrix.to) - [Project website](http://matrix.to) - [README](https://github.com/matrix-org/matrix.to/blob/main/README.md) - [Releases](https://github.com/matrix-org/matrix.to/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/matrix-org-matrix-to