Run MeshVault Server
with Docker.

Choose the setup for your host.

You need a running Docker installation with Docker Compose, a persistent folder for your models, and enough free space for your library and previews. On Windows or macOS, use Docker Desktop with Linux containers. On a Linux server or compatible NAS, use its Docker/Compose tools.

The published image is ghcr.io/xalies/meshvault-server-amd64:latest, for Intel/AMD x86-64 hosts. There is currently no native ARM64 Docker image. The container includes its .NET runtime; you do not need to install .NET on the host.

Choose one configuration for your server. The examples use the same container name, so run one at a time. Use these examples on a trusted local network and keep port 5225 within that network.

Start with Docker Compose.

1. Create a folder for this Docker setup, such as meshvault-server.
2. Download docker-compose.server.yml into that folder. You can also copy the configuration below into a file with that exact name.
3. Create a MeshVaultLibrary folder beside it, or replace ./MeshVaultLibrary with the host path to your existing library. Keep the destination /library unchanged.
4. Open a terminal in the setup folder and run the start commands below.

services:
  meshvault-server:
    image: ghcr.io/xalies/meshvault-server-amd64:latest
    container_name: meshvault-server
    restart: unless-stopped
    ports:
      - "5225:5225"
      - "127.0.0.1:5226:5226"
    environment:
      MESHVAULT_LIBRARY: /library
      MESHVAULT_SERVER_CONFIG: /data/meshvault-server.json
      XDG_DATA_HOME: /data
      MESHVAULT_SERVER_URLS: http://0.0.0.0:5225;http://0.0.0.0:5226
      MESHVAULT_DOCKER_ADMIN_PORT: "5226"
      # Optional: set this to a 6-digit PIN if you do not want the server to generate one.
      # MESHVAULT_SERVER_PIN: "123456"
    volumes:
      - ./MeshVaultLibrary:/library
      - meshvault-server-data:/data

volumes:
  meshvault-server-data:

The PIN example is commented out so the server generates one for you. If you enable it, replace 123456 with your own six-digit PIN before starting.

docker compose -f docker-compose.server.yml pull
docker compose -f docker-compose.server.yml up -d
docker compose -f docker-compose.server.yml logs --tail=100 meshvault-server

Look for Server PIN: in the logs, then open the library and sign in.

Use a persistent NAS folder.

For a Linux Docker host, including compatible TrueNAS SCALE and Unraid setups, download docker-compose.host-network.yml. Use this file instead of the bridge file.

Replace ./MeshVaultLibrary in the service's volumes list with your real dataset or share path. For example:

    volumes:
      - "/mnt/tank/models/MeshVault:/library"
      - meshvault-server-data:/data

On Unraid, the library might be a share such as /mnt/user/3D Models/MeshVault. Keep the quotes around paths containing spaces. The host folder must be writable by the container: MeshVault stores its database and images alongside your models.

docker compose -f docker-compose.host-network.yml pull
docker compose -f docker-compose.host-network.yml up -d
docker compose -f docker-compose.host-network.yml logs --tail=100 meshvault-server

If your NAS provides a container dashboard, use its Compose/custom-app support with this configuration and read the PIN from the container logs.

Host networking uses port 5225 directly and allows mDNS discovery on the LAN. Leave out ports: mappings and make sure another service is not using that port. Docker Desktop users should keep the bridge setup and use a manual IP connection.

Open your library and unlock the server.

1. Find the generated Server PIN in the container logs. For a bridge setup, you can also view it at http://localhost:5225/config on the Docker host; this redirects to the local administration port.
2. On that host, open http://localhost:5225. From another device, open the host's LAN address, for example http://192.168.1.20:5225. Replace the example IP with your server's address.
3. Enter the PIN when prompted. The browser library is now available.
4. Open Options → Licence, paste your MeshVault licence key and select Unlock server. The direct address is http://HOST-IP:5225/config#licence.

Current Server builds start with a seven-day trial. After the trial, browsing remains available; importing, scanning, editing and generating thumbnails require an activated Pro licence. Keep the /data storage when updating so the server retains its activation.

Get a MeshVault licence if you need one. The licence is USD $19.99, includes lifetime updates and is not limited to a product version. Store pricing and taxes may vary.

Add files, then refresh.

Upload through the browser library or send downloads with MeshVault Connect. You can also copy models and creator packs directly into the host folder mapped to /library.

After copying files outside MeshVault, click Refresh in the browser library. This scans the folder and generates missing thumbnails. Allow time for larger libraries and complex models; restarting the container is not a substitute for generating missing thumbnails.

The server reuses available artwork and embedded previews before rendering a fallback. A file being listed in the library does not guarantee an interactive preview or a generated thumbnail for every format.

The Docker server's thumbnail generation uses the CPU. You do not need to configure GPU passthrough. Interactive browser previews run in the connecting browser, so their performance also depends on that device.

For simultaneous access from several computers, connect the desktop clients to the server. Keep one server responsible for the library rather than opening the same database as separate local libraries on multiple devices.

Use a PIN or individual accounts.

Single-user mode uses the server PIN. If you want separate sign-ins, open Options → Mode & users from trusted local administration, create the Owner account and enable named-user mode. You can then add Browse, Manage or Owner accounts for the same library.

Initial account setup requires host-local administration; an ordinary LAN PIN session cannot enable it. Once enabled, sign in with a username and password. Owners manage server settings and licensing. The local administration port does not bypass account sign-in.

ssh -L 15225:127.0.0.1:5225 user@NAS-IP

Accounts, sessions and personal user data are stored in /data. Preserve that storage alongside the library. Each client must support the server's chosen sign-in mode.

Back up both storage locations.

Before a backup, finish active imports and stop the server. Back up the entire library, including hidden files, plus the contents of the data volume using your Docker/NAS backup tools. A models-only backup does not include your library organisation; a library-only backup does not include the host's accounts and activation.

docker compose -f docker-compose.server.yml stop

Once the backup of both storage locations is complete, start the server again:

docker compose -f docker-compose.server.yml start

Use docker-compose.host-network.yml in those commands if that is your configuration. Restore both storage locations before starting a replacement server. Keep the same mappings; selecting a new empty folder or volume will not restore the old data.

For Docker's volume backup and restore procedure, see Back up, restore or migrate data volumes.

Update the image. Keep the mounts.

Take a current backup, finish active work, and run these commands from the same setup folder:

docker compose -f docker-compose.server.yml pull
docker compose -f docker-compose.server.yml up -d
docker compose -f docker-compose.server.yml logs --tail=100 meshvault-server

For host networking, use docker-compose.host-network.yml instead. Pull downloads the image; up -d recreates the container with the existing mounts. Restarting an old container alone does not install a new image.

Keep the Compose project name, setup directory and storage mappings consistent. Changing them can select a different data volume. For a fixed version, replace :latest with an available numeric release tag, without a leading v.

To stop without removing data, use docker compose -f docker-compose.server.yml stop. Avoid down -v when you want to retain the server: it removes the named data volume and its saved settings, accounts and activation.

docker load -i meshvault-server-image.tar.gz

Check the connection, path and logs.

Still stuck? Contact MeshVault support with your server version, host/NAS type, network mode, mount layout and the relevant error. Remove PINs, licence keys and other credentials from logs or screenshots before sharing them.

The settings in your Compose file.

Further Docker help: bind mounts, Compose networking and host networking.