Build a private model registry first, verify it locally, then expose only the required HTTP endpoint
MatrixHub is an open-source, self-hosted AI model registry designed as a private, Hugging Face-compatible hub for inference workflows such as vLLM and SGLang. This guide explains how to choose between its documented Docker Compose and Helm deployment paths, prepare the installation, validate the running service, and avoid common configuration mistakes. Once MatrixHub works correctly on its private network, we show how to publish its HTTP service through Localtonet without configuring inbound router port forwarding, firewall rules, a VPN, or a public IP address. Exact MatrixHub listener ports and deployment commands must come from the installation documentation associated with the version you deploy because the available project evidence does not establish stable values that can safely be hardcoded here.
📋 What's in this guide
How the MatrixHub and Localtonet architecture works
MatrixHub is a self-hosted registry for storing, organizing, caching, and distributing AI model assets. Its project describes it as a private replacement for Hugging Face that is designed around large inference workloads. It supports Hugging Face-compatible access, including the use of the HF_ENDPOINT environment variable to point compatible software at a MatrixHub deployment instead of the public Hugging Face service.
The important architectural distinction is that MatrixHub owns the model-registry workflow, while Localtonet provides an optional network path to the already running service. Localtonet does not install MatrixHub, configure its storage, create projects, or replace MatrixHub authentication. The correct order is therefore to deploy MatrixHub, confirm that it works from the local network, apply appropriate access controls, and only then create an HTTP tunnel.
HF_ENDPOINT. The exact endpoint value must match the reachable base URL of your deployment.
For a single-host evaluation, Docker Compose is generally the simpler documented deployment family. MatrixHub v0.2.0 uses SQLite by default for its Docker Compose deployment, while MySQL remains available through an explicit Compose configuration. For a Kubernetes environment, MatrixHub provides a Helm path. The same release notes state that Helm and Kubernetes deployments do not support SQLite, so those deployments need the database arrangement established by the project’s current chart and installation guide.
| Deployment path | Best fit | Important consideration |
|---|---|---|
| Docker Compose with SQLite | Single-node evaluation or a comparatively simple private deployment | SQLite is the documented default for Docker Compose in MatrixHub v0.2.0. |
| Docker Compose with MySQL | A Compose deployment where an explicit MySQL configuration is preferred | MySQL requires the project’s explicit Compose configuration rather than the default SQLite path. |
| Helm on Kubernetes | Cluster-based deployment and Kubernetes operations | SQLite is not supported for Helm or Kubernetes deployments. |
MatrixHub clients, browsers, inference workers, and Localtonet must ultimately address the same intended service. An internal hostname may work inside a cluster but not on the machine running the Localtonet client. Record the actual reachable address and mapped port produced by your deployment instead of assuming a default.
Prepare the host and deployment plan
Begin by deciding where the registry, model data, database, and Localtonet client will run. For Docker Compose, the Localtonet client can run on the same host as MatrixHub or on another device that can reach the published MatrixHub HTTP listener. For Kubernetes, it can run on a device with a valid network route to the exposed service. It does not need direct access to every pod, but it must be able to connect to the HTTP address selected as the tunnel’s local target.
Install and validate the container or cluster tooling required by the MatrixHub deployment path you choose. Docker Compose requires a functioning Docker installation with Compose support. Helm requires a working Kubernetes cluster, access credentials with the permissions needed for the intended namespace, and a functioning Helm installation. Those tools should be operational before MatrixHub files are applied.
Storage capacity deserves particular attention. AI model repositories can contain very large files, and a registry that caches upstream assets can grow over time. Select a durable location with sufficient capacity and define how it will be backed up. If you use NFS or S3-compatible storage, test access from the MatrixHub runtime before depending on it for production data. Storage availability and permissions should be treated separately from remote HTTP connectivity.
You should also decide how the registry will be named and reached. Keep separate records for the following addresses:
- The container or pod address used only inside its runtime network.
- The host, service, or load-balancer address reachable by local clients.
- The public HTTPS address assigned to the Localtonet HTTP tunnel.
These addresses may be different. A container-only hostname is not automatically reachable from the host, and a Kubernetes service name is not automatically resolvable outside its cluster. The Localtonet target must be an IP address and port reachable from the device running our client.
The supplied project evidence does not establish a stable local hostname, listener port, container port mapping, or verification URL. Use the installation material shipped with the MatrixHub version you deploy and inspect the resulting Compose or Kubernetes configuration. Hardcoding an unverified port could expose the wrong service or produce a tunnel that never connects.
Prepare an access and authentication policy
MatrixHub documents role-based access control, project isolation, and audit logging. Decide who should administer the registry, who can upload or modify content, and who only needs read access. Project viewers should not receive editor or administrator privileges merely because remote access is convenient. MatrixHub v0.2.0 also distinguishes public and private project types, so check project visibility before publishing any route to the service.
Do not reuse public demonstration credentials in a private installation. The project’s hosted demo is intended for evaluation and may be reset. A self-hosted environment should use its own credentials, tokens, robot accounts, and SSH keys according to the current MatrixHub configuration.
Select and pin a MatrixHub release
Avoid treating a moving development branch as a fixed deployment specification. Select a release, review its release notes, and use the installation files associated with that version. MatrixHub v0.2.0 introduced material deployment changes, including SQLite as the Docker Compose default, optional MySQL Compose configuration, and configurable SSH port exposure. It also contains security-related dependency updates and input-hardening changes.
The v0.2.0 release container is described as keylessly signed with Cosign and accompanied by an SPDX software bill of materials. If supply-chain verification is part of your deployment policy, follow the exact verification instructions attached to the selected release rather than copying commands from an unrelated image version.
Install MatrixHub with Docker Compose or Helm
MatrixHub’s official project directs users to its installation guide for the supported Docker Compose and Helm commands. The available evidence for this article confirms those deployment families but does not include the complete command sequence, repository checkout requirements, chart values, image references, namespaces, or port mappings. We therefore do not reproduce commands that cannot be verified. The following workflow explains what must be selected, applied, and checked around the documented installer.
Open the MatrixHub project repository, select the release you intend to deploy, and follow the Installation material associated with that version. Do not mix a Compose file from one release with a configuration example from another.
Docker Compose deployment workflow
Choose the Compose database mode
Use the documented default SQLite deployment for a single-node setup, or deliberately select the explicit MySQL Compose configuration when that database architecture is required. Do not assume the two configurations have identical persistence requirements.
Keep the release configuration together
MatrixHub v0.2.0 prepares config.yaml in the same folder as docker-compose.yml. Preserve the release’s expected file placement and review configuration values before starting the deployment.
Define persistent storage
Confirm where registry data, model files, and database state will persist. Check ownership, available capacity, mount behavior, and backup coverage before uploading important model assets.
Run the documented Compose installation
Apply the exact Docker Compose command from the selected MatrixHub release documentation. After startup, inspect container state and logs through your Docker tooling. Resolve failed dependencies or storage errors before continuing.
Record the published HTTP listener
Read the effective Compose configuration and note the host-side IP address and port mapped to MatrixHub. This verified host-side listener, not an assumed container port, is the value needed for local testing and a later Localtonet tunnel.
If the deployment includes configurable SSH Git access, treat that endpoint independently from the web interface. MatrixHub v0.2.0 supports SSH Git access for model repositories with public-key authentication and configurable SSH port exposure. An HTTP tunnel is for the web or HTTP API service. It does not automatically publish an SSH listener, and this guide does not configure an SSH tunnel.
Helm and Kubernetes deployment workflow
Confirm cluster and namespace access
Verify that the chosen Kubernetes context is the intended cluster and that the deployment identity can create the resources required by the MatrixHub chart.
Plan the supported database and storage
Do not use SQLite for a Helm deployment. Select the database and persistent storage configuration documented by the current MatrixHub chart, including suitable persistent volume behavior for model data.
Review chart values for the selected release
Examine image versions, persistence settings, service exposure, database settings, and any authentication-related values. Avoid applying values copied from a different MatrixHub release without checking compatibility.
Install with the documented Helm command
Run the exact Helm procedure in the official MatrixHub installation material for the chosen version. Wait for the workloads and required stateful services to become ready before testing the application.
Create a reachable local service path
Identify the Kubernetes service address, ingress address, load-balancer address, or other documented local access method that the Localtonet client device can reach. A cluster-only service name is insufficient when our client runs outside that cluster.
MatrixHub explicitly directs users to versioned installation instructions, but the evidence supplied for this draft does not contain those commands or their required values. Omitting them prevents an unverified image, chart name, port, path, or namespace from being presented as authoritative. Before publication, the exact commands should be validated against the selected MatrixHub release documentation.
Configure the registry for private model workflows
Once MatrixHub is running, finish application-level setup before creating public connectivity. Sign in using credentials created or documented for your own deployment, not credentials from the public demonstration environment. Review the available administrative settings, establish the intended users or automation identities, and create the project structure needed for your model repositories.
MatrixHub v0.2.0 supports creating and managing MatrixHub-type registries in its registry management interface. When creating projects and registries, check the registry base URL carefully. The release adds provider-specific hints and warnings for values that resemble an individual repository rather than a registry base. A base URL should identify the appropriate service root expected by MatrixHub, not an arbitrary model page.
Choose project visibility and roles deliberately
Use private projects for content that should be limited to approved users or service accounts. Assign viewer access to identities that only need to read or download models, editor access only where modification is required, and administrative access sparingly. MatrixHub’s release notes confirm that project viewers do not receive the Create Model action, while project administrators and editors do.
For automation, use purpose-specific credentials rather than a personal administrator account. MatrixHub supports robot accounts, access tokens, and SSH public keys. Keep those secrets out of Compose files, screenshots, shell history, tunnel configuration, and article examples. The public URL created later is an address, not a substitute for authorization.
Configure model storage and caching
Confirm that the configured storage backend can create, read, and update the required objects or files. A successful web login does not prove that large model uploads or cache operations will succeed. Test with non-sensitive data first, observe capacity, and verify that the data remains after a controlled service restart.
MatrixHub is designed to cache upstream models so multiple consumers can reuse local copies. That can reduce repeated external transfers, but cached content still consumes storage and needs lifecycle planning. Monitor growth, document retention expectations, and back up the data and metadata required to restore the registry.
Point compatible clients at MatrixHub
MatrixHub documents HF_ENDPOINT as the mechanism for directing compatible Hugging Face workflows to the registry. Set its value to the MatrixHub base URL reachable from the specific client. A process inside the same private network may use an internal address, while a remote process may use the assigned Localtonet HTTPS address after the tunnel is configured.
Do not set remote production clients to the Localtonet address until browser and API verification has succeeded. Also confirm whether each application honors HF_ENDPOINT, because client behavior can vary by library and version. MatrixHub provides separate integration guidance for vLLM, SGLang, llm-d, Dynamo, and model distribution workflows.
Verify MatrixHub locally before opening remote access
Local verification separates registry problems from tunnel problems. If MatrixHub does not respond directly on its private address, a tunnel cannot repair the application, database, storage, or container configuration.
Confirm the application workload is running
Use the selected container or Kubernetes management tools to check that the MatrixHub application and its required dependencies are healthy. Review recent logs for startup, migration, database, storage, and binding errors.
Test the verified local address
Open the actual host or service URL established by the deployment. Test from the MatrixHub host first, then from the device that will run the Localtonet client if it is a different machine.
Complete an authenticated workflow
Sign in with an account created for the private deployment. Confirm that authorized pages are available and that unauthorized users do not receive unintended access.
Create or cache a non-sensitive test model
Follow MatrixHub’s Getting Started workflow to cache the first model or create an appropriate test repository. Confirm that metadata and model content are stored successfully.
Test a compatible client
Point a supported test client’s HF_ENDPOINT at the local MatrixHub base URL and verify the intended read or download operation. Use non-sensitive test content until the access model has been validated.
Record the exact working local IP address and port after these tests. For example, distinguish between a browser URL that works only through an administrator’s temporary port-forwarding session and a durable service address reachable by the Localtonet client. The latter is required for stable remote access.
A connection refusal, timeout, database error, or application error on the local MatrixHub address must be fixed in MatrixHub or its infrastructure first. Start Localtonet integration only after the same device that will run our client can reach the service directly.
Expose the working MatrixHub HTTP service with Localtonet
After local verification, an HTTP tunnel is the appropriate Localtonet family for the MatrixHub web or HTTP API service. Our client establishes an outbound connection to a Localtonet relay server. The resulting tunnel provides a public HTTPS address without requiring an inbound router port-forwarding rule, firewall change, VPN setup, or public IP address.
The public address forwards traffic to the local IP address and port you verified in the previous section. Keep MatrixHub authentication enabled because the tunnel makes the endpoint reachable but does not replace application authorization.
Install and run the Localtonet client
Install our client on the MatrixHub host or another device that can reach the verified MatrixHub HTTP listener. Keep the client running for as long as remote access is required.
Authenticate and select the device
Use the device-specific authentication token supplied through your Localtonet account. Select the connected client device that can reach MatrixHub. Never place the token in documentation, logs, screenshots, or shared configuration.
Select an available relay server
Choose a currently available server or region from the dashboard. Availability can vary, so obtain the value from the current product instead of relying on a hardcoded server code.
Create the HTTP tunnel
Configure an HTTP tunnel whose local target is the verified MatrixHub IP address and host-side port. For Process Type, choose Random Sub Domain, Custom Sub Domain, or Custom Domain as appropriate and available. All three process types serve the target content through a public HTTPS address.
Start the tunnel
Press Start after reviewing the target. Creating the tunnel alone does not make it run. The selected client must remain connected, and the tunnel must remain in its running state.
Test the assigned public URL
Open the assigned HTTPS address from a separate network, authenticate to MatrixHub, and repeat a limited read operation. If remote applications will use MatrixHub, test the public base URL with the intended compatible client only after browser access succeeds.
The current configuration workflow is also summarized in our Localtonet HTTP tunnel documentation. If you choose a custom domain, verify the current DNS requirements in our documentation before changing production DNS. Those requirements should not be inferred from generic tunnel examples.
MatrixHub must remain available at the configured local target, and the selected Localtonet client must remain connected with the tunnel running. If either side stops, the public endpoint cannot serve the registry.
Secure the registry and remote endpoint
A model registry can contain proprietary weights, internal metadata, access tokens, and artifacts with significant operational value. Treat remote publication as a security boundary change, even when the service was already protected by MatrixHub authentication.
| Control | Where it applies | Recommended practice |
|---|---|---|
| MatrixHub authentication | Web, API, model, and project access | Require individual or automation-specific identities and remove default or evaluation credentials. |
| Project roles | Model and project authorization | Use viewer access for read-only consumers and reserve editor or administrator access for approved operators. |
| Project visibility | Private versus broadly visible content | Review every project’s visibility before enabling remote access. |
| Secret handling | MatrixHub and Localtonet credentials | Do not embed tokens, passwords, private keys, or device tokens in public files or URLs. |
| Storage protection | Models, database state, and cached assets | Restrict host permissions, monitor capacity, and maintain tested backups. |
| Tunnel lifecycle | Public network reachability | Stop or delete the tunnel when remote access is no longer required. |
Expose only the MatrixHub HTTP listener needed for the intended workflow. Do not point the tunnel at a Docker daemon, database, object-store administration interface, Kubernetes control plane, or unrestricted host dashboard. If SSH Git access is required, assess it as a separate service with public-key authentication and its own access policy rather than assuming that the HTTP tunnel covers it.
Keep MatrixHub updated through a controlled release process. Review release notes for database migrations, configuration changes, dependency security updates, and image verification information. Back up persistent state before an upgrade, test the new version privately, and verify local functionality again before restarting public access.
Audit activity at both the application and infrastructure layers. MatrixHub documents comprehensive audit trails for upload and download activity. Preserve relevant logs according to your organization’s retention policy, but avoid collecting secrets in plaintext. Remote access should complement these controls, not weaken them.
Keep private projects private, enforce MatrixHub authorization, and share credentials only with approved users or automation. Localtonet provides connectivity to the configured service. It does not authorize users inside MatrixHub or bypass organizational network policies.
Troubleshoot installation and remote-access problems
MatrixHub does not open locally
Check whether the application workload and its required database are running. Review logs for configuration parsing, database migration, storage permission, address binding, and dependency failures. Confirm that you are testing the host-side address produced by the deployment rather than a container-only or cluster-only address.
With Docker Compose, inspect the effective port mapping and verify that another process is not occupying the intended host port. With Kubernetes, confirm that the pods are ready and that the selected service path has endpoints. If the service is reachable only from inside the cluster, establish a documented network path that the Localtonet client can use.
The web interface works, but models cannot be stored
A functioning interface does not establish that persistent storage is writable. Check filesystem or object-storage credentials, mount ownership, capacity, quotas, and network connectivity to NFS or S3-compatible storage. Confirm that the registry metadata database and model object storage are both persistent.
The tunnel starts, but the public URL fails
Test the local target from the exact device running the Localtonet client. If that device cannot reach the configured IP address and port, change the local network route or select a reachable MatrixHub listener. Verify that the client remains connected, the intended tunnel is running, and the target has not changed following a restart.
A common container mistake is to configure a host target using an address that exists only inside the Compose network. A similar Kubernetes mistake is using a service DNS name from a client outside the cluster. Replace it with an address that is genuinely reachable from the Localtonet client while preserving appropriate network restrictions.
The public page opens, but authentication or generated links fail
First confirm that the same operation works through the local MatrixHub URL. Then review MatrixHub’s base URL and proxy-related settings for the exact deployed version. The available evidence does not define their names or required values, so do not invent settings. Use the current MatrixHub configuration reference and verify that generated links use the intended external scheme and host.
A Hugging Face-compatible client still contacts the public service
Confirm that HF_ENDPOINT is set in the environment of the actual process, container, pod, or service account running the client. Setting it in an interactive shell does not necessarily change an already running service. Restart the client process if its configuration is read only during startup, and check that the library version honors the variable.
Downloads time out or are interrupted
Large model transfers depend on MatrixHub health, storage performance, the Localtonet client connection, the selected relay, and the remote client’s network. Test the same object locally to separate storage or application problems from remote-path problems. Avoid assuming a performance guarantee, because throughput varies with deployment resources, networks, relay availability, file size, and workload.
Access stopped after a restart
Check MatrixHub first, including its current host-side listener. Then verify that the Localtonet client is connected and the tunnel is running. A tunnel exists as a saved configuration even when it is stopped, and it is available only while the selected client and tunnel are active.
Frequently asked questions
What is MatrixHub?
MatrixHub is an open-source, self-hosted AI model registry designed as a private, Hugging Face-compatible hub. It is intended for storing, caching, organizing, and distributing model assets, including workflows involving vLLM and SGLang.
Should I install MatrixHub with Docker Compose or Helm?
Docker Compose is the simpler documented family for a single-host deployment. MatrixHub v0.2.0 uses SQLite by default for Docker Compose and provides an explicit MySQL configuration. Helm is intended for Kubernetes deployments, where SQLite is not supported.
Which MatrixHub port should I enter in Localtonet?
Use the host-side or service port produced by your verified MatrixHub deployment. This article does not provide a default because the available project evidence does not establish a stable listener or port mapping. Inspect the installation configuration for the version you deployed and test that address from the Localtonet client device.
Does Localtonet install or configure MatrixHub?
No. MatrixHub must already be installed, configured, and reachable locally. With Localtonet, we provide the remote network path to the selected local HTTP address after the registry is working.
Does an HTTP tunnel replace MatrixHub authentication?
No. The tunnel provides connectivity to MatrixHub. Keep application authentication, project visibility rules, role-based authorization, and audit controls enabled. Use least-privilege identities for users and automation.
Can a remote Hugging Face-compatible client use the Localtonet address?
Yes, when the client supports HF_ENDPOINT and the Localtonet HTTPS address correctly reaches the MatrixHub HTTP service. Verify the public URL and authentication first, then set the remote process’s endpoint to the appropriate MatrixHub base URL.
Does the MatrixHub tunnel remain online permanently?
The endpoint is available only while MatrixHub is reachable, the selected Localtonet client is connected, and the tunnel is running. Creating a tunnel does not start it automatically. You can stop or delete it when remote access is no longer required.
Can the same HTTP tunnel publish MatrixHub SSH Git access?
No. MatrixHub’s SSH Git access is a separate protocol and listener. The HTTP tunnel described here publishes only the web or HTTP API target. Evaluate SSH access separately, retain public-key authentication, and expose only the service that is actually required.
Connect your verified MatrixHub deployment with Localtonet
After MatrixHub is working on its private address, install our client on a device that can reach it, create an HTTP tunnel for the verified listener, and test the assigned HTTPS URL with least-privilege MatrixHub credentials.
Get Started Free →
