Install Medusa Locally and Share It with Localtonet

Understand what you are installing

Medusa is a commerce platform with a framework and modules for building custom commerce applications. Its core commerce modules are open source and available through npm, while Enterprise Edition materials are identified separately by the project. The platform is intended for applications such as direct-to-consumer stores, B2B commerce, marketplaces, distributor platforms, point-of-sale systems, and other services that need reusable commerce primitives.

A local Medusa installation and a public tunnel solve different problems. Medusa supplies the commerce application and its local HTTP service. Localtonet supplies the route from a public address to that service. Installing Localtonet does not install, configure, or start Medusa, and creating a tunnel does not repair an application that is unavailable locally.

Keep those responsibilities separate throughout the workflow. First, install Medusa using instructions that match the selected Medusa release. Next, start the application and identify the exact address and port it reports. Test that address from the device that will run our client. Only after those checks pass should you configure the HTTP tunnel.

Prepare the local host and installation plan

Installation requirements for actively maintained JavaScript applications can change between releases. The supplied Medusa repository evidence directs local users to the project's Documentation learning section, but it does not establish the exact runtime version, package manager command, database setup, operating-system support matrix, default credentials, default port, or startup command for a new local application. We therefore will not invent any of those values.

Before entering installation commands, choose the Medusa release or documentation version you intend to use. The supplied evidence includes release v2.21.2, but that does not mean it will remain the newest release. A reproducible setup should use instructions compatible with the version selected for the project rather than combining commands from unrelated releases.

Information to confirm in the current Medusa documentation

• The supported operating systems and any platform-specific restrictions.
• The required JavaScript runtime and its supported version range.
• The package manager and project creation command recommended for the selected release.
• Any database or external service required by the local application.
• Required environment variables and the format of their values.
• The documented development startup command.
• Whether the generated project contains more than one independently started web service.
• The address, port, and path that should be used for the first health check.

Use an ordinary, non-administrative development account where the operating system permits it. Make sure the account can create project files and install the documented dependencies. Also confirm that the host has enough free storage for source files, dependencies, build output, and any local data services required by the selected setup.

Decide where the application will live before generating it. Avoid placing the project in a temporary directory or a synchronized folder unless the Medusa documentation explicitly supports that workflow. Record the chosen application directory because startup and maintenance commands will normally need to run in the correct project context.

Install Medusa using version-matched instructions

Begin with the local setup path in Medusa's current documentation. The repository explicitly sends developers there to set up a Medusa application locally. Follow that documented sequence without substituting package-manager commands from memory or from an older Medusa generation.

The exact command sequence is intentionally not reproduced here because it is absent from the supplied project evidence. That evidence also does not establish whether the current setup wizard installs every dependency, creates a database, asks interactive questions, or starts multiple services. Supplying plausible commands would make this guide look complete while creating a meaningful risk of giving you an invalid or unsafe installation.

Capture the installation result

While following the current setup instructions, record the details that will matter later:

• The full path to the generated project.
• The Medusa version selected or installed.
• The runtime and package-manager versions actually used.
• The names of required local supporting services.
• The documented command for starting the application in development mode.
• Whether an administrative interface, backend service, or storefront starts separately.
• The local URLs printed after startup.

Preserve the package lockfile created by the selected package manager. It records the resolved dependency graph and helps other developers reproduce the environment. Do not casually delete or regenerate it while diagnosing an unrelated networking issue.

Distinguish a project checkout from an application installation

Medusa's source repository contains the platform code, packages, tests, scripts, and contribution resources. Cloning that repository is not necessarily the same workflow as creating a local commerce application. If your goal is to build a store or evaluate Medusa, use the application's documented learning or setup path. Use the repository contribution workflow only when your goal is to work on Medusa itself and the project explicitly instructs you to do so.

This distinction matters because repository development may require a different dependency layout, additional tooling, integration tests, or contributor-specific startup procedures. Localtonet can expose any reachable HTTP process, but it cannot determine whether you started the correct Medusa project type.

Configure the Medusa application before exposing it

Complete the configuration required by the selected Medusa installation guide before thinking about public access. A tunnel transports requests to an existing listener. It does not supply missing database connectivity, generate application secrets, initialize commerce data, or select appropriate production settings.

Keep sensitive values out of committed source files. If the documented Medusa workflow uses environment files, secret stores, or runtime environment variables, follow that mechanism exactly. Do not paste Medusa credentials, database passwords, Localtonet device tokens, or private endpoints into screenshots, issue reports, shell history examples, or public repositories.

Identify the service that should be shared

A commerce development environment can contain multiple web-facing components. Do not assume that every locally printed URL should be made public. Decide whether the remote user needs the backend API, a storefront, an administrative interface, or another application generated alongside Medusa. Each independently listening service has its own local address and port and may require a separate tunnel.

The evidence available for this article does not identify Medusa's current default local port or a guaranteed health-check endpoint. Obtain the real values from the running application's terminal output and the current Medusa documentation. This prevents a common failure in which a correctly configured tunnel points at the wrong local service.

Start and verify Medusa locally

Run the documented Medusa startup command from the correct project directory. Keep the terminal visible during the first launch so that you can inspect startup messages rather than assuming the process is ready. If the application reports a migration, database, dependency, or configuration error, resolve that error before configuring Localtonet.

Record the authoritative local endpoint

When startup succeeds, copy the address and port reported by the application. Do not replace them with a remembered default. For example, if the application reports a loopback address, record that exact host and port. If it reports a LAN address or wildcard binding, determine which concrete address the Localtonet client can use.

Test the documented page or endpoint in a browser on the same device. A successful verification should demonstrate more than an open port. Confirm that the response belongs to the intended Medusa component, that expected assets load, and that the terminal does not begin reporting repeated server-side failures.

Test from the Localtonet client's network context

The easiest arrangement is to run our client on the same device as Medusa. In that case, a loopback listener can normally be targeted from that device. If our client runs on another machine, container host, virtual machine, or subsystem, a service bound only to the Medusa host's loopback interface will not automatically be reachable from the client device.

For a separate client device, verify local network reachability before creating the tunnel. Use an address that belongs to the Medusa host and that is reachable from the Localtonet client. Adjusting a service's listening interface or host firewall can expand who can reach it, so make those changes only when the project's documentation and your network policy permit them.

Share the working Medusa service with Localtonet

Once the required Medusa component works from the Localtonet client's device, use an HTTP tunnel for that web service. Our client establishes an outbound connection to a Localtonet relay server, so you do not need inbound router port forwarding, a public IP address, firewall port-opening rules, or VPN setup for this tunnel workflow.

HTTP tunnels point to a local IP address and port. HTTP process types include Random Sub Domain, Custom Sub Domain, and Custom Domain, and each serves the configured content at a public HTTPS address. Availability of particular options, servers, regions, or capabilities can vary, so use the choices currently shown in your dashboard rather than relying on a hardcoded server code.

For the current interface and configuration details, consult our HTTP tunnel documentation. The local target must still come from your own verified Medusa process rather than from an example value.

Secure the public development endpoint

A local development listener is normally available to a limited network context. Publishing it changes the exposure boundary because anyone who can reach the assigned public address can send requests to the application. Treat the public URL as an internet-facing endpoint even if you intend to share it with only one collaborator.

Keep Medusa's own authorization controls enabled. A tunnel provides connectivity, not application-level identity, role enforcement, or permission design. Use strong credentials and least-privilege accounts for any interface that supports authentication. Never assume that an obscure URL is an access-control mechanism.

Expose only the necessary component

If a collaborator needs a storefront preview, do not automatically expose a separate admin service. If an integration needs one API, review whether publishing the entire development interface is appropriate. Separate services can be given separate lifecycle decisions, and an unnecessary tunnel should remain stopped.

Protect secrets and private data

Development commerce databases may contain test customer records, tokens, order information, email addresses, integration credentials, or copied production data. Use synthetic data whenever possible. Do not use a public development tunnel to expose a database port, secret-management service, internal dashboard, or unrestricted debugging endpoint.

Do not publish Localtonet device tokens. Tokens identify client devices and must not be guessed, embedded into a Medusa repository, or included in support screenshots. If a token is exposed, handle it through the relevant account controls rather than continuing to treat it as private.

Understand the HTTPS boundary

HTTP process types provide a public HTTPS address. This should not be described as proof that every part of the application architecture uses end-to-end encryption. The local target remains the IP address and port you configured, and its transport depends on the local service and selected tunnel configuration. Do not make unsupported security or compliance assumptions based only on the public URL.

Operate the local application and tunnel

During routine use, think of Medusa and Localtonet as two independently managed processes. Start Medusa first and verify its local URL. Then start our client and the tunnel. This order makes failures easier to diagnose because you establish that the target works before adding remote routing.

When ending a session, stop the tunnel if the endpoint should no longer be public. Then stop the local development process according to the project's documented procedure. Deleting a tunnel is appropriate when you no longer need its configuration, while stopping it preserves the configuration for later use.

Restart sequence

1. Start any supporting services required by the documented Medusa setup.
2. Start the intended Medusa component with its documented command.
3. Verify the recorded local URL and check the application output.
4. Start or confirm the Localtonet client connection.
5. Start the HTTP tunnel.
6. Test the assigned public address.

If Medusa starts on a different port after a configuration change, update the tunnel target before testing again. A previously working public URL cannot route correctly when its configured local destination no longer matches the active listener.

Upgrading Medusa

Follow Medusa's release notes when updating the project. Review runtime requirements, configuration changes, data migrations, and integration compatibility before upgrading. Preserve a recoverable copy of important development data and configuration according to the project's guidance.

After an upgrade, repeat local verification before restarting public access. Do not use a successful tunnel connection as proof that the upgraded application is healthy. A tunnel can be active while its target returns errors or serves the wrong component.

Troubleshoot local and remote access

Diagnose problems from the inside out. Start with the Medusa process, then test the local endpoint, then confirm reachability from the Localtonet client, and finally inspect tunnel state and the public request. This sequence prevents a local application failure from being misdiagnosed as a tunneling issue.

Separate HTTP errors from connectivity errors

An application-generated HTTP error means the request reached some web server. Check the Medusa logs, requested path, authentication state, and application configuration. A connection failure usually points earlier in the chain, such as a stopped process, wrong port, unreachable bind address, disconnected client, or stopped tunnel.

Check browser-dependent behavior

If the basic public page loads but interactive behavior fails, inspect the browser's network and console output. Absolute URLs, allowed origins, cookies, callbacks, and secure-context expectations can affect applications accessed through a new public hostname. The correct setting names and values are Medusa-version-specific, so take them from the current project documentation rather than adding guessed environment variables.

Do not solve application errors by widening exposure

Disabling authentication, exposing additional internal ports, or binding every service to all interfaces can hide the original diagnosis while creating new risks. Keep the tunnel target narrow and repair the failing application dependency or configuration directly.

Frequently asked questions