Skip to content

Self-Host MatrixHub on Kubernetes with Helm + Localtonet

Install MatrixHub on Kubernetes with Helm, verify the web console and Hugging Face endpoint, then reach your private model registry remotely over HTTP.

Summary in your language
In this article 13 sections
Self-Hosting · MatrixHub · Localtonet · 2026

Run a private Hugging Face-compatible model registry on your cluster, then reach it from outside the LAN

MatrixHub is an open-source, self-hosted AI model registry that acts as a drop-in private replacement for Hugging Face and is built to speed up vLLM and SGLang workloads. This guide installs it on Kubernetes with the official Helm chart, shows how to read the chart's real settings for storage, an external database and service exposure, verifies the deployment from the command line and the browser, and walks through the proxy-project caching flow. After that we add Localtonet as a separate step, so teammates, laptops and remote inference nodes can reach the registry over a public HTTPS address without router port forwarding.

🔒 Model weights stay on your own storage 🌐 HTTP tunnel to the web console and HF endpoint ⚡ Helm install from an OCI chart
Illustration of a private MatrixHub registry in a Kubernetes cluster connected through an HTTP tunnel to a remote laptop
MatrixHub runs as a private model registry inside your cluster and can be reached remotely through an HTTP tunnel.

What MatrixHub is and why you might self-host it

Once models move from experiments to production, the weights themselves become assets you have to govern. Pulling them from the public internet on every node, every restart and every deployment wastes bandwidth and ties critical systems to an external service. MatrixHub is built for that gap. Its project describes it as an open-source, self-hosted AI model registry for large-scale enterprise inference, and compares itself to Hugging Face the way Harbor compares to Docker Hub.

In practice that means you run a registry inside your own network, store model weights on your own storage, and point your existing tooling at it by changing the Hugging Face endpoint instead of rewriting training or inference code.

🔁 Transparent Hugging Face proxy Set the HF_ENDPOINT environment variable to your MatrixHub address and the training and inference code can stay unchanged.
📦 On-demand caching Public models are pulled once and then served locally, which reduces repeated traffic to the public internet.
🛡️ RBAC and audit logs The project lists fine-grained permissions, project-based isolation and audit trails for uploads and downloads.
💾 Storage flexibility The project describes support for local filesystems, NFS and S3-compatible backends. The Helm chart currently uses PVC-backed storage, with S3-compatible object storage planned for a future release.
☸️ Kubernetes and inference integration The project positions MatrixHub alongside vLLM, SGLang and Kubernetes. NVIDIA's Dynamo documentation also has a guide for loading models from a MatrixHub endpoint.
Check you have the right MatrixHub

More than one project uses this name. The one in this guide is the model registry from the matrixhub-ai GitHub organization, installed from the OCI chart at ghcr.io/matrixhub-ai/matrixhub. A separate site called MatrixHub describes an open catalog of MCP servers, agents and tools with its own desktop client and CLI. That project is unrelated to this guide, and its installation steps will not give you a model registry.

Helm or Docker Compose: choosing the install path

Side-by-side diagram comparing a single-host Docker Compose setup with a Helm deployment on a Kubernetes cluster
Docker Compose targets a single host, while Helm deploys MatrixHub into a Kubernetes cluster.

The official installation page names two supported methods: Docker Compose for single-node hosts, and Helm charts for Kubernetes clusters. This article focuses on Helm because that is the path for a cluster, and it covers the Compose commands in full so a single-server reader can finish the job here too.

Aspect Docker Compose Helm on Kubernetes
Intended target A standalone virtual machine or server A Kubernetes cluster
Default database SQLite, with no separate database service (since v0.2.0). MySQL is available through a separate Compose file. MySQL. SQLite is not supported on Helm/Kubernetes deployments.
Default web console address http://127.0.0.1:3001, changeable with MATRIXHUB_HTTP_PORT http://<node-ip>:30001 when installed with the NodePort setting shown below
Data location ./data/matrixhub for SQLite, on a local filesystem, one instance only PVC for data (50Gi default) and PVC for built-in MySQL (8Gi default)

Docker Compose on Linux or macOS

The documented commands pin a released version, download two files, and start the stack with SQLite:

export MATRIXHUB_VERSION=v0.2.0
mkdir -p matrixhub && cd matrixhub
curl -fL \
  "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$MATRIXHUB_VERSION/deploy/docker-compose.yml" \
  -o docker-compose.yml
curl -fL \
  "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$MATRIXHUB_VERSION/deploy/config.yaml" \
  -o config.yaml
MATRIXHUB_IMAGE_TAG="$MATRIXHUB_VERSION" docker compose up -d

Docker Compose on Windows (PowerShell)

$env:MATRIXHUB_VERSION = "v0.2.0"
New-Item -ItemType Directory -Force -Path "matrixhub" | Out-Null
Set-Location "matrixhub"
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$env:MATRIXHUB_VERSION/deploy/docker-compose.yml" `
  -OutFile "docker-compose.yml"
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$env:MATRIXHUB_VERSION/deploy/config.yaml" `
  -OutFile "config.yaml"
$env:MATRIXHUB_IMAGE_TAG = $env:MATRIXHUB_VERSION
docker compose up -d

Replace v0.2.0 with the version you want to run. If port 3001 is already in use, set MATRIXHUB_HTTP_PORT before starting the stack: export MATRIXHUB_HTTP_PORT=3002 on Linux and macOS, or $env:MATRIXHUB_HTTP_PORT = "3002" in PowerShell. The web console then opens at http://127.0.0.1:3001 (or your chosen port). SQLite data is stored in ./data/matrixhub. Run only one MatrixHub instance against that database and keep it on a local filesystem.

Docker Compose with MySQL instead of SQLite

To use MySQL on a single host, the installation page tells you to download docker-compose.mysql.yml and config-mysql.yaml instead of the SQLite pair. The reference page lists the MySQL configuration as deploy/config-mysql.yaml, so the files come from the same deploy directory as the SQLite ones. Then start the stack with the MySQL Compose file:

curl -fL \
  "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$MATRIXHUB_VERSION/deploy/docker-compose.mysql.yml" \
  -o docker-compose.mysql.yml
curl -fL \
  "https://raw.githubusercontent.com/matrixhub-ai/matrixhub/$MATRIXHUB_VERSION/deploy/config-mysql.yaml" \
  -o config-mysql.yaml
MATRIXHUB_IMAGE_TAG="$MATRIXHUB_VERSION" docker compose -f docker-compose.mysql.yml up -d

In PowerShell, download the same two files with Invoke-WebRequest as shown above, then run $env:MATRIXHUB_IMAGE_TAG = $env:MATRIXHUB_VERSION followed by docker compose -f docker-compose.mysql.yml up -d. The public MatrixHub demo and the default Helm deployment both use MySQL, so this variant is the closest single-host match to a cluster install.

Everything later in this guide about verification, the Hugging Face endpoint and Localtonet applies to a Compose install as well. The local target for the tunnel is then the Compose host and port 3001 (or your chosen port) instead of a Kubernetes node port.

Prerequisites for the Helm install

The chart README lists three requirements, and the installation page adds the storage detail you need to act on:

  • Kubernetes 1.19 or newer.
  • Helm 3.8 or newer, because the chart is pulled from an OCI registry.
  • A default StorageClass, or explicit storage settings for the PVCs the chart creates.

MatrixHub publishes the chart to GitHub Container Registry (ghcr.io) as an OCI artifact, so the machine running Helm needs outbound access to it. Your cluster nodes also need to pull the container images the chart deploys. You do not need a documentation page to learn which images those are. Render the chart locally and list them after you choose a version (the commands are in the configuration section), then mirror them if your cluster is restricted.

Check your tool versions and the StorageClass before installing:

kubectl version
helm version
kubectl get storageclass

The StorageClass check matters most. The Helm chart currently supports PVC-backed storage for MatrixHub data. If no StorageClass is marked as default and you do not provide storage settings, the PVCs cannot bind and the pods wait. Development clusters with no StorageClass at all can use the chart README section titled "Development-only Local Storage Setup", which exists precisely for that case. Treat it as a way to get a throwaway lab running and not as a production design. For anything people depend on, use a real StorageClass or an existing PVC backed by durable storage.

Plan the database before you install

The default Helm deployment includes a built-in MySQL instance, deployed as a StatefulSet with volume claim templates as of v0.2.0. The chart also supports using an external database, and the README has a dedicated "Use an External Database" section. If you want the database managed outside the chart, or you want data to survive a reinstall, decide that now and set it at the first install. The configuration section below shows how to find the exact settings.

Install MatrixHub with Helm

Four-step flow from Helm chart to install command to running pods to a MatrixHub service
The Helm install moves from chart to running pods and an exposed MatrixHub service.

The official installation page installs the chart from the OCI registry and exposes the service through a NodePort. The steps below follow that sequence.

1

Confirm storage is ready

Run kubectl get storageclass and make sure a default StorageClass exists. If it does not, plan explicit storage settings for the PVCs the chart creates before continuing.

2

Set the chart version and namespace

Export the two variables used by the install command. The official example uses chart version 0.1.1 and the namespace matrixhub. For a newer stable release, replace 0.1.1 with the chart version you want to run.

3

Install the chart

Run helm install against the OCI chart with the NodePort service type. The --create-namespace flag creates the namespace if it does not exist.

4

Find a node IP and open the UI

List the nodes with kubectl get nodes -o wide, then open http://<node-ip>:30001 in a browser on a machine that can reach the node.

The commands for steps 2 and 3 are:

export CHART_VERSION=0.1.1
export NAMESPACE=matrixhub

helm install matrixhub oci://ghcr.io/matrixhub-ai/matrixhub \
  --version "$CHART_VERSION" \
  --namespace "$NAMESPACE" --create-namespace \
  --set apiserver.service.type=NodePort

A few details about this command are worth understanding rather than copying blindly:

  • Service type. The README lists ClusterIP as the default service type and NodePort as the alternative. Without --set apiserver.service.type=NodePort, the service is reachable only inside the cluster.
  • Storage sizes. The MatrixHub data PVC defaults to 50Gi and the built-in MySQL PVC defaults to 8Gi. Change them with --set apiserver.storage.pvc.size=100Gi and --set mysql.persistence.size=20Gi. Size the data volume for the models you plan to cache, since model weights are large.
  • Chart version and application version. The installation page uses chart 0.1.1 as its example while the latest GitHub release is v0.2.0. Helm records the application version a chart deploys in the chart's own metadata, so you can resolve the pairing directly instead of guessing. Run helm show chart oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION" and read the version and appVersion fields. Do this before you assume your install includes v0.2.0 features such as the Compose SQLite default or the SSH Git access settings.
  • Pods are named by the chart. Names depend on the release name you choose (here, matrixhub), so identify them from your own kubectl get pods output and use those names in later commands.
Uninstalling removes data by default

The official documentation states that helm uninstall removes resources including the default PVCs created by the chart. If you want model data to survive an uninstall or reinstall, use an existing PVC for MatrixHub data and an external database from the start, rather than discovering this later.

Chart values, storage, external database and service exposure

The one-line install is fine for a lab. A production-grade install needs choices about where data lives, where the database lives and how the service is exposed. The chart README groups these under Configuration, Preset Models, Storage (Default StorageClass, Specify a StorageClass, Use an Existing PVC, Use an External Database, Development-only Local Storage Setup) and Exposing the Service (ClusterIP, NodePort). The documentation site also has a Reference page that prints the default Helm values.yaml next to the Compose configuration files.

The values you can set with certainty from the official installation page are these three:

Value Default or example What it controls
apiserver.service.type ClusterIP by default, NodePort in the official install Whether the application is reachable only inside the cluster or on a node port. The official NodePort install serves the console on 30001.
apiserver.storage.pvc.size 50Gi Size of the PVC that holds MatrixHub data, which includes the model files.
mysql.persistence.size 8Gi Size of the PVC for the built-in MySQL StatefulSet.

Keep your settings in a values file

Once you set more than one or two values, move them out of --set flags into a file that you keep in version control (without secrets). Using only the keys above, the equivalent of the earlier command with larger volumes is:

apiserver:
  service:
    type: NodePort
  storage:
    pvc:
      size: 100Gi
mysql:
  persistence:
    size: 20Gi
helm install matrixhub oci://ghcr.io/matrixhub-ai/matrixhub \
  --version "$CHART_VERSION" \
  --namespace "$NAMESPACE" --create-namespace \
  -f matrixhub-values.yaml

Read the full set of values from the chart itself

The keys for a StorageClass, an existing PVC, an external database, SSH port exposure and any ingress settings live in the chart's values.yaml, which is the same file the Reference page prints. Helm can show it to you for the exact version you are installing, so the answer always matches your chart:

# Full default values for your chart version
helm show values oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION" > default-values.yaml

# Chart metadata, including appVersion
helm show chart oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION"

# The chart README, with Configuration and Preset Models sections
helm show readme oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION"

# Jump to the settings this guide discusses
grep -n -i -E "storageClass|existingClaim|persistence|pvc" default-values.yaml
grep -n -i -E "mysql|database|dsn|host|password" default-values.yaml
grep -n -i -E "ssh|nodePort|ingress|service" default-values.yaml

Copy default-values.yaml, keep only the keys you want to change, and pass the result with -f. Do not edit keys you do not understand, and never put real passwords in a file you commit. For database credentials use whatever secret mechanism your cluster standard prescribes and the key names the values file shows.

A note on exact key names

The sources we could read for this revision give us the three keys in the table above, the section structure of the README and the list of options. The remaining key names (for a StorageClass, an existing claim, external database connection details and SSH port exposure) differ by chart version, so take them from helm show values for your version rather than from a blog post. That is the one place this guide defers to the chart.

Storage choices

Goal README section Practical guidance
Use whatever the cluster provides Default StorageClass The install uses the cluster's default StorageClass for the data and MySQL PVCs. Fine for trials.
Choose a specific class, such as faster disks for the database Specify a StorageClass Set the class through values, using the key names from your default-values.yaml.
Keep model data across uninstall and reinstall Use an Existing PVC Create the PVC yourself, with a size and class suited to model weights, then reference it by name in values. Helm will not delete a claim it did not create.
Keep metadata outside the release Use an External Database Point the chart at a MySQL you operate. Back it up with your standard database tooling.
Lab cluster with no StorageClass Development-only Local Storage Setup Only for throwaway environments. Not a production design.

Model files and database rows are two halves of one state. MatrixHub stores repository content on the data volume and metadata such as projects, users and registries in the database. If you use an existing PVC for data and an external database, you can uninstall and reinstall the chart without losing either. If you move only one of them out, a reinstall leaves you with files that no database record describes, or the reverse. Treat them as a pair when you back up and when you restore.

Exposing the service

The README documents two exposure modes: ClusterIP (the default) and NodePort. Beyond those, you have standard Kubernetes options:

  • NodePort, as installed above. Simple and predictable, with the console on port 30001 of every node. Make sure node firewalls allow the port only from networks you trust.
  • ClusterIP plus kubectl port-forward for administration and short tests, without opening any node port. The forward ends when the command ends.
  • ClusterIP plus an Ingress from your own ingress controller, if your cluster already standardizes on one. Search default-values.yaml for ingress keys to see whether your chart version offers built-in settings. If it does not, write the Ingress resource yourself and point it at the MatrixHub service name and port that kubectl get svc reports. An Ingress rule that matches on a host name only receives requests carrying that Host header, so keep that in mind when you choose it as the local target for a tunnel.

If your chart version exposes an SSH port setting for Git over SSH (added in v0.2.0 for Compose and Helm), you will find it in the same default-values.yaml. SSH Git access is a separate protocol from the web console, which matters for tunneling later.

Verify the deployment locally before exposing it

Terminal showing running pods beside a browser displaying the MatrixHub web console on localhost
Confirm the pods are running and the web console loads locally before exposing anything.

Do not add a tunnel to something you have not confirmed works on the local network. Proving it locally first narrows any later problem down to either the install or the remote path.

Check the Kubernetes objects

helm status matrixhub --namespace "$NAMESPACE"
kubectl get deploy,statefulset,pods,pvc,svc --namespace "$NAMESPACE"

Use the workload names from that output to wait for the rollout. The built-in MySQL is a StatefulSet and the application is a separate workload:

kubectl rollout status statefulset/<mysql-statefulset-name> --namespace "$NAMESPACE" --timeout=300s
kubectl rollout status deployment/<matrixhub-deployment-name> --namespace "$NAMESPACE" --timeout=300s

# Or wait for every pod in the namespace at once
kubectl wait --for=condition=Ready pod --all --namespace "$NAMESPACE" --timeout=300s

What you want to see:

  • A MySQL pod and a MatrixHub application pod, all Running and ready.
  • A service of type NodePort for the application, with node port 30001 as in the official example.
  • PVCs in the Bound state (data 50Gi and MySQL 8Gi unless you changed them). A PVC stuck in Pending usually means there is no default StorageClass or the requested class cannot provision.

Read the real service port and node port from the cluster, since you need them for port-forward and for later tunnel decisions:

kubectl get svc --namespace "$NAMESPACE" \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.type}{"\t"}{range .spec.ports[*]}{.port}{" -> nodePort "}{.nodePort}{"  "}{end}{"\n"}{end}'

List the images the pods actually run, which also tells you what your nodes must be able to pull:

kubectl get pods --namespace "$NAMESPACE" \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.image}{"  "}{end}{"\n"}{end}'

Open the web console

Get a node address with kubectl get nodes -o wide and open http://<node-ip>:30001 from a machine on the same network. From a terminal:

curl -I http://<node-ip>:30001
curl -s -o /dev/null -w "%{http_code}\n" http://<node-ip>:30001/

A 200 response, or a redirect to a login page, confirms the NodePort path to the application works. If you prefer not to open a node port at all, forward the service to your workstation using the service port reported above:

kubectl port-forward --namespace "$NAMESPACE" svc/<service-name> 8080:<service-port>
# then browse to http://127.0.0.1:8080

Read the logs

Application logs are the first place to look when the console loads but something behind it fails. For the Helm install use kubectl logs deployment/<matrixhub-deployment-name> --namespace "$NAMESPACE" --tail=100, adding -f to follow. For Compose use docker compose logs --tail=100 from the directory holding the Compose file. MySQL logs come from the MySQL pod in the same way.

First login and the proxy project workflow

Signing in for the first time

The installation page and release notes do not publish a default administrator username or password, and this guide does not make one up. After install, open the console and look at what your version presents: either a sign-in form whose initial credentials are defined by your configuration (the Compose pair ships a config.yaml and a config-mysql.yaml, and the Helm chart ships its values.yaml) or a first-run account flow. Read those files for your version, set strong credentials before anything is reachable beyond a trusted network, and create named accounts for people rather than sharing one. The Reference page prints the default Compose configuration files and the default Helm values, which is where any initial account setting would appear.

How caching through a proxy project works

The installation page ends with "Cache models through a proxy project" as the first thing to do after install. The idea is straightforward even without the click-by-click detail. MatrixHub has registries and projects. A registry describes an upstream source, and the registry creation form has a Base URL field with provider-specific hints and defaults (and a warning if the address looks like a single repository rather than a registry root). A project is the namespace that holds models and carries the access rules. A proxy project points at a registry, so a request for a model that is not stored yet is fetched from that upstream, kept locally, and served from the local copy afterwards. That is the "pull once, serve all" behavior behind the on-demand caching feature.

The workflow, as far as the official material describes it, is:

1

Create a registry for the upstream source

In the registry management area, add a registry and choose its provider. Accept or adjust the suggested Base URL and avoid pointing it at one specific model repository. The release notes also say MatrixHub-type registries can be created and managed here.

2

Create a project that targets that registry

When you create a project, pick the target registry. If none exists yet, the creation flow guides you to create one. Choose public or private deliberately, because the console now explains what each visibility level means.

3

Add members with the right roles

New project members default to the Viewer role. Only project administrators and editors see the Create Model action, so grant roles by need.

4

Request a model through HF_ENDPOINT

From a client, set HF_ENDPOINT to MatrixHub and download a small model. The first request populates the cache, and later requests are served from your storage. The cluster needs outbound access to the upstream registry for that first fetch.

Where the official detail stops

The sequence above reflects the registry-first, project-second flow that the v0.2.0 release notes describe. The exact field labels and the way a project is marked as a proxy depend on your console version, so follow the on-screen form for those. Test with a small model such as Qwen/Qwen3-0.6B before you cache anything large.

Point a Hugging Face client at MatrixHub

MatrixHub's core compatibility promise is that a Hugging Face client keeps working when its endpoint is redirected. The project's own description is to set HF_ENDPOINT to MatrixHub and leave training and inference code unchanged.

Cache a model through the registry

NVIDIA's Dynamo documentation shows the pattern for pre-caching a model, run from a host that can reach your MatrixHub deployment. The hf command comes from the Hugging Face Hub client, which you install separately (for example with pip install -U huggingface_hub).

HF_ENDPOINT="http://<node-ip>:30001" hf download Qwen/Qwen3-0.6B

On Windows PowerShell, set the variable first:

$env:HF_ENDPOINT = "http://<node-ip>:30001"
hf download Qwen/Qwen3-0.6B

In the Dynamo example, the endpoint is an in-cluster MatrixHub address on port 30001, and the guide treats the model repository as pre-cached before the deployment starts. Replace the address with your own endpoint and the model with the one you need.

Use it from inference workloads

In the Dynamo example, the inference container receives HF_ENDPOINT as an environment variable pointing at MatrixHub, and the model is then loaded from the registry instead of from the public Hugging Face service. The same idea applies to any workload that honors HF_ENDPOINT. If you change the model, make sure the repository exists in MatrixHub or can be fetched through your proxy project first. NVIDIA states that the timings in its guide were measured in one environment with one model and a warm image cache, and are not a general benchmark. Measure your own network instead of relying on published figures.

Private projects and tokens

A public project can be read without signing in. For a private project, the client must authenticate. Hugging Face clients conventionally read a token from the HF_TOKEN environment variable and send it with each request. MatrixHub's profile page has an access token creation button, and robot accounts exist for automation. Create a token for the workload, give its account the lowest role that works, set it as HF_TOKEN on the client, and test with a small model. If the download is rejected, check the account's project role first.

Reach MatrixHub remotely with a Localtonet HTTP tunnel

Diagram of a remote browser reaching a MatrixHub service in a Kubernetes cluster through a Localtonet HTTP tunnel
Request path from a remote client through a Localtonet HTTP tunnel to MatrixHub running in a private cluster.
Diagram of a remote client reaching MatrixHub in a private Kubernetes cluster through a Localtonet HTTP tunnel
Remote requests reach the public endpoint, travel through the HTTP tunnel, and arrive at the MatrixHub service.

Everything above works for machines on the same network as your cluster. The remote-access problem appears when a data scientist works from home, when a contractor needs to pull a model, or when an inference node in another site needs to load weights. Opening a router port and publishing a node's address directly is possible, but it needs a public IP, firewall changes and care about exposure. With Localtonet, the client on a device that can reach MatrixHub makes an outbound connection to our relay server, and the tunnel provides a public HTTPS address. No inbound port forwarding, firewall changes or VPN setup are required, and the tunnel exists only while the client is connected and the tunnel is running.

Do this only after local verification passes. MatrixHub is served over HTTP, so the HTTP tunnel type is the relevant one, and it carries the web console and the Hugging Face-compatible HTTP endpoint.

The request path, hop by hop

Knowing which hop uses which protocol makes the choice of local target obvious. This is the path a remote hf download takes:

Hop From and to Protocol and TLS
1 Remote client (HF_ENDPOINT set to the tunnel address) to the Localtonet public address HTTPS. The public address is the HTTPS side of the tunnel, so this is the leg that crosses the internet.
2 Localtonet relay to the Localtonet client on your device Carried over the outbound connection the client opened to the relay. Nothing is opened inbound on your network.
3 Localtonet client to the local target, for example <node-ip>:30001 Plain HTTP on your own network, because the local target is the MatrixHub HTTP port.
4 NodePort to the MatrixHub application pod HTTP inside the cluster, through the Kubernetes service.
5 MatrixHub to the built-in MySQL StatefulSet (8Gi PVC) or your external database Database connection inside the cluster, for metadata such as users, projects and registries.
6 MatrixHub to the data PVC (50Gi by default) Volume access for repository content and model files.

Two practical consequences follow. First, HTTPS ends before your service, so the last hops are plain HTTP on a network you control. Run the Localtonet client close to the cluster and keep that segment on a trusted network. Second, you enter the HTTP address of the service as the tunnel target (a node IP and 30001, or a forwarded local port), never an https:// address and never the database or the volume.

Decide where the Localtonet client runs

A Localtonet HTTP tunnel points to a local IP address and port that is on, or reachable from, the device running the client. For MatrixHub there are three distinct arrangements:

Client location Local target to enter Consideration
A separate host on the node network (a server, VM or workstation) <node-ip> and port 30001 Uses the documented NodePort. The host must be able to reach the node and must stay online for the tunnel to work. Choose a node that is reliably up.
An admin workstation running kubectl port-forward 127.0.0.1 and the local port you forwarded Works when no node port is reachable. The forward must keep running, so it suits testing more than a long-lived setup.
The Docker Compose host 127.0.0.1 and port 3001, or your MATRIXHUB_HTTP_PORT For single-server installs, the client runs on the same machine as MatrixHub and the tunnel targets the loopback address.

For the port-forward option, reuse the service name and service port you read earlier, and confirm the console loads in a browser at the forwarded address before creating the tunnel:

kubectl port-forward --namespace "$NAMESPACE" svc/<service-name> 8080:<service-port>

Create and start the tunnel

Follow the standard HTTP tunnel workflow and keep the current Localtonet HTTP tunnel documentation open alongside it, since dashboard labels can change between releases. Client installers for each operating system are on the Localtonet download page.

1

Install the Localtonet app

Install the app for your operating system on the device that can reach MatrixHub, from the download page, and connect it using that device's auth token from your dashboard. Treat the token as a secret and keep it out of tickets, chat and repositories.

2

Open the HTTP tunnel page

In the dashboard, go to the HTTP tunnel page to create a new tunnel.

3

Select the Process Type

Choose Random Sub Domain, Custom Sub Domain or Custom Domain. The table below helps you pick. Use a random subdomain for a first test.

4

Select the AuthToken and server

Pick the auth token of the device that will run the tunnel and choose a relay server from the list the dashboard currently offers. Do not rely on a fixed list of regions.

5

Enter the local IP and port

Enter the MatrixHub target from the client-location table, for example the node IP and 30001, or 127.0.0.1 and your forwarded or Compose port. Confirm that address opens in a browser on the client device first.

6

Press Start

Creating a tunnel does not run it. Start it, then open the public HTTPS address in a browser and confirm the MatrixHub console loads. Stop or delete the tunnel when it is no longer needed.

Process Type What it gives you Good fit for
Random Sub Domain A generated subdomain serving the content at a public HTTPS address Quick tests and verifying that the setup works
Custom Sub Domain A subdomain you select, where supported A predictable address to share with a team
Custom Domain Your own domain name in front of the tunnel A stable registry hostname. Check the current Localtonet documentation for DNS requirements before configuring it.

Use the public address from a remote machine

Once the tunnel is running, the registry address you give to Hugging Face clients is the public tunnel URL rather than the node IP:

HF_ENDPOINT="https://<your-tunnel-address>" hf download Qwen/Qwen3-0.6B
$env:HF_ENDPOINT = "https://<your-tunnel-address>"
hf download Qwen/Qwen3-0.6B

As with the local test, the model must already exist in MatrixHub or be reachable through your proxy project. Start with a small model to confirm the full path works, then move on to larger ones.

Tokens and private projects over a public hostname

When a client sends HF_TOKEN to a private project through the tunnel, the token travels in request headers. On the internet leg it is protected by HTTPS. On the final hop from the Localtonet client to MatrixHub it is plain HTTP, which is why the client should sit on a trusted segment close to the cluster. Use short-lived or narrowly scoped tokens and robot accounts per workload so you can disable one without affecting others. Revoke tokens that were pasted anywhere they should not have been. If you can, test a private-project download from a machine on a different network, with no cached session, before announcing the address.

Set expectations for large downloads

Model weights are big, and they now travel over the internet through a relay instead of across your local network. We have not verified upload-size, bandwidth or rate limits for HTTP tunnels on any plan, so none are claimed here, and the throughput figures on the MatrixHub website describe intranet distribution, not a tunneled path. Test a representative model and your real client locations before relying on a remote setup for production loads. For clusters that load weights at deploy time, point those in-cluster workloads at the internal address and keep the tunnel for people and remote sites.

What an HTTP tunnel does not cover

The v0.2.0 release added SSH Git access to model repositories, with a configurable SSH port exposure for Docker Compose and Helm deployments. SSH is not HTTP, so an HTTP tunnel does not carry it. A raw TCP tunnel is a separate Localtonet tunnel type, and the SSH Git case with MatrixHub has not been validated for this guide. If you need Git over SSH remotely, treat it as separate work and test it yourself. For most remote use cases, the web console and the Hugging Face-compatible HTTP endpoint are what you need.

Security checklist before you publish a registry

A tunnel makes a service reachable. It does not decide who is allowed to use it, and it does not bypass authorization or network policy. A model registry may hold proprietary fine-tuned weights, so the application's own access controls are your main protection. Work through these points before sharing the public address with anyone.

  • Set strong credentials first. Review the configuration for your version, make sure no default or guessable credentials remain, and create named accounts for people.
  • Use project visibility deliberately. The console explains public and private project types before you pick one. Keep anything sensitive in a private project.
  • Apply least privilege. New project members default to the Viewer role, and the Create Model action is limited to project administrators and editors. Give people the lowest role that does the job.
  • Prefer robot accounts for automation. Robot accounts enforce disabled and expired states and all-project permissions. Manually specified robot tokens must be 8 to 20 characters and include at least one uppercase letter, one lowercase letter and one number. Create one robot per workload.
  • Use the audit trail. The project lists audit logs for uploads and downloads. Review them after you open remote access.
  • Restrict who can reach the tunnel. In the tunnel's settings in the Localtonet dashboard, look for access restriction options such as IP restrictions and apply them if your tunnel offers them, limiting access to your office, VPN or known remote sites. Confirm the available options in the current documentation, as they can vary by plan and tunnel type.
  • Limit the network behind the tunnel. Allow the Localtonet client host to reach only the MatrixHub port it needs. Keep the database and volumes off any externally reachable address.
  • Stop the tunnel when it is not needed. A stopped tunnel is not reachable. For occasional remote access, starting and stopping the tunnel shrinks the exposure window.
  • Keep the software current. The v0.2.0 notes include hardening for malformed namespace and token inputs, author filters that could reach outside the configured storage directory, and updates to Go and quic-go for known vulnerabilities. An old version is a real risk for a public endpoint.
Never expose an unauthenticated registry

If you cannot confirm that sign-in is enforced and that sensitive projects are private, do not start the public tunnel. Test from a device on a different network, with no existing session, to confirm that anonymous visitors see only what you intend.

Verify the container image signature

The v0.2.0 release states that its container image is keylessly signed with Cosign and carries an attached SPDX SBOM. If your policy requires verifying images before deployment, the release page gives these commands for that version:

cosign verify \
  --certificate-identity-regexp 'https://github.com/matrixhub-ai/matrixhub/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/matrixhub-ai/matrixhub:v0.2.0

cosign download sbom ghcr.io/matrixhub-ai/matrixhub:v0.2.0

These commands apply to the image tag named in the release. Use the image list from the verification section to see which tag your chart version actually runs, and verify that tag.

Day-two operations

Inspect and change settings

To see what the release was installed with, and to change settings later, use standard Helm commands. These are general Helm behavior, not MatrixHub-specific features:

helm get values matrixhub --namespace "$NAMESPACE"

helm upgrade matrixhub oci://ghcr.io/matrixhub-ai/matrixhub \
  --version "$CHART_VERSION" \
  --namespace "$NAMESPACE" \
  --reuse-values \
  --set apiserver.storage.pvc.size=100Gi

Whether a PVC can be resized in place depends on your StorageClass allowing volume expansion, so check that before depending on it. Read release notes before upgrading across versions, since the v0.2.0 notes include changes to how the chart deploys MySQL (a StatefulSet with volume claim templates). Render the new version first with helm template or a dry run, and compare it with what is running.

Back up and preserve data

Because uninstalling removes the default PVCs, treat chart-managed volumes as disposable unless you have decided otherwise. For anything you care about, use an existing PVC for MatrixHub data and an external database. Then back up both with your cluster's own tooling: CSI volume snapshots or your backup product for the data volume, and your normal MySQL dump or snapshot procedure for the database. Take them close together in time, and rehearse a restore into a scratch namespace to confirm that a restored database and restored files agree. For a Compose install, the SQLite data lives in ./data/matrixhub, so stop the stack before copying that directory.

Upgrade

Pin the version in both the chart and the image. For Compose, set MATRIXHUB_VERSION and MATRIXHUB_IMAGE_TAG to the new tag, re-download the Compose and config files for that tag, and run docker compose up -d again. For Helm, run helm upgrade with the new --version, then repeat the rollout and PVC checks.

Uninstall

helm uninstall matrixhub --namespace "$NAMESPACE"

This removes the default PVCs the chart created, but not an existing PVC or external database you supplied. Also stop and delete the Localtonet tunnel pointing at the registry if you are decommissioning it, so the public address no longer maps to a stale target.

Keep the tunnel path healthy

Localtonet offers a platform-wide webhook system that fires when a token or tunnel in a selected Token Group changes to Connected or Disconnected, with a JSON body containing the id, date, type and status. If a remote team depends on the registry, a webhook to your chat or monitoring system gives early notice that the client has disconnected. See the Localtonet webhook documentation for the details. Run the client on a host that restarts reliably, because the tunnel only works while that client is connected.

Troubleshooting

Symptom Likely cause What to check
helm install fails to pull the chart Helm older than 3.8, or no outbound access to ghcr.io Run helm version and test network access from the machine running Helm.
Pods stay Pending, PVCs stay Pending No default StorageClass, or storage settings the cluster cannot satisfy Run kubectl get storageclass and kubectl describe pvc. Set explicit storage, or use the development-only local storage section for lab clusters.
Pods in ImagePullBackOff Nodes cannot reach the image registry List the images with the jsonpath command above, then mirror them or open egress for the nodes.
Application pod restarts or waits on the database MySQL not ready, or wrong external database settings Run kubectl rollout status on the MySQL StatefulSet and read the application logs. For an external database, recheck host and credentials in your values file.
Service not reachable on port 30001 Service left as ClusterIP, wrong node IP, or a firewall in front of the node Run kubectl get svc and confirm NodePort. Confirm node firewall or security-group rules allow the port from where you test.
Local console works, public address fails Tunnel created but not started, client disconnected, or wrong local target Check the tunnel is running and the client is connected. Re-test the exact local IP and port from the client device.
Public address loads but login or downloads fail Credentials, project visibility or role problems, or the model is not in the registry Sign in locally with the same account, check project roles, and confirm the model repository exists or is proxied.
First download of a model is slow or fails, later ones are fast Upstream fetch through the proxy project is the slow part, or the cluster has no outbound access to the upstream registry Check the registry Base URL, egress from the cluster, and the application logs during the first request.
Very large downloads break over the tunnel Long transfers over a relayed internet path Retry with a small model to prove the path, then test the large one. Use the internal address for in-cluster workloads.
Copy buttons do nothing in the console Older version served over plain HTTP The v0.2.0 notes say copy buttons now work over HTTP. Upgrade, or use the HTTPS tunnel address.
Docker Compose port 3001 already in use Another service holds the port Set MATRIXHUB_HTTP_PORT to a free port before starting the stack.

A systematic approach

Test one layer at a time, from the inside out. First confirm the pods and PVCs are healthy. Then confirm the NodePort (or forwarded port) answers from the machine that will run the Localtonet client. Then confirm the tunnel is running and the client is connected. Finally test from a machine on a different network. When the problem sits between two of those layers, you know which boundary to examine. Application logs from kubectl logs (or docker compose logs) are the next place to look for application-level errors.

Known limits worth remembering

  • SQLite is not supported on Helm/Kubernetes deployments. If a guide tells you to use it there, it does not apply.
  • The Helm chart supports PVC-backed storage for data. S3-compatible object storage in the chart is described as planned, not available.
  • The SQLite database used by Compose should have one MatrixHub instance on a local filesystem.
  • The project's public website carries a "Coming Soon" banner, and v0.2.0 was the latest release at the time of writing. Evaluate it as an actively developed but young project, and pin versions in production.

Frequently asked questions

How do I install MatrixHub on Kubernetes with Helm?

You need Kubernetes 1.19 or newer, Helm 3.8 or newer, and a default StorageClass. Install the OCI chart with helm install matrixhub oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION" --namespace "$NAMESPACE" --create-namespace --set apiserver.service.type=NodePort, then open http://<node-ip>:30001. The official example uses chart version 0.1.1 and namespace matrixhub.

Which port should the Localtonet HTTP tunnel point to?

For the documented Helm NodePort install, the local target is a node IP that the Localtonet client can reach, with port 30001. For a Docker Compose install, use 127.0.0.1 and port 3001 unless you changed MATRIXHUB_HTTP_PORT. If you use kubectl port-forward, use the local port you forwarded. Confirm the target in a browser from the client device before creating the tunnel.

Can I use SQLite with the Helm chart?

No. SQLite support is for single-node deployments, with Docker Compose using it by default, and Helm/Kubernetes deployments do not support SQLite. The default Helm deployment uses a built-in MySQL StatefulSet, and the chart supports an external database through its README's "Use an External Database" option.

Will my data survive helm uninstall?

Not with the default setup. Uninstalling removes resources including the default PVCs the chart created. To preserve data, use an existing PVC for MatrixHub data and an external database, both set at the first install.

How do I find the chart values for an existing PVC or an external database?

Run helm show values oci://ghcr.io/matrixhub-ai/matrixhub --version "$CHART_VERSION" to print the default values.yaml for your exact chart version, and helm show readme for the matching README sections. Search the values for storage, claim, mysql and database keys, then override only those in your own values file.

Does an HTTP tunnel make the registry safe to share publicly?

A tunnel only makes the service reachable. It does not replace authentication or authorization. Use MatrixHub's own accounts, project visibility, roles and robot accounts, avoid default or weak credentials, apply any access restrictions your tunnel offers, and stop the tunnel when you do not need remote access.

Does the HTTP tunnel also carry Git over SSH?

No. MatrixHub v0.2.0 added SSH Git access with a configurable SSH port, but SSH is a different protocol from HTTP. An HTTP tunnel serves the web console and the HTTP endpoint only. A TCP tunnel for SSH Git has not been validated here, so test it yourself if you need it.

Where does HTTPS end when I use a Localtonet tunnel with MatrixHub?

The public tunnel address is HTTPS, and your local target is MatrixHub's HTTP port, so the final hop from the Localtonet client to the node port is plain HTTP on your own network. Keep the client close to the cluster on a trusted segment, and treat tokens sent to private projects accordingly.

Start with Localtonet

Once your MatrixHub registry answers on the local network, create an HTTP tunnel with Localtonet and give remote teammates and inference nodes a public HTTPS address for it, without opening a router port.

Get Started Free →

Corrections & updates

Substantive changes approved by the Localtonet editorial team are listed transparently below.

Reviewed and updated for accuracy and completeness.

Localtonet is a secure multi-protocol tunneling and proxy platform designed to expose localhost, devices, private services, and AI agents to the public internet supporting HTTP/HTTPS tunnels, TCP/UDP forwarding, mobile proxy infrastructure, file server publishing, latency-optimized game connectivity, and developer-ready AI agent endpoint exposure from a single unified control plane.

Support