Install with Docker

This guide covers setting up MASV Engine (formerly MASV Agent) using Docker. For native installation on your operating system, see the platform-specific guides for Linux, macOS, or Windows.

Supported architectures

MASV Engine supports multiple architectures for deployment in different environments. Use the getmasv/masv-engine:3.2.15 image tag to automatically pull the correct architecture for your system.

Architecture	Tag
x86-64	3.2.15
arm64	3.2.15

Caution

Always pin to a specific version tag in production environments for reproducible deployments. Check Docker Hub for the latest available version.

Pulling the image

Ensure that Docker is installed on the host machine, then pull the MASV Engine image:

docker pull getmasv/masv-engine:3.2.15

Volume configuration

MASV Engine stores configuration and transfer data in two directories. Use Docker volumes to make these persistent across container restarts.

Volume	Purpose
/config	Application configuration and saved transfer state
/data	Default mount point for automated downloads and uploads

Create matching directories on the Docker host before starting the container:

mkdir ~/masv-engine
mkdir ~/masv-files

Tip

Create these directories before starting the container. Otherwise, Docker creates them with root as the owner.

Container startup

Docker CLI

docker run -d \
  --name masv-engine \
  -u 1000:1000 \
  -v ~/masv-engine:/config \
  -v ~/masv-files:/data \
  --restart unless-stopped \
  getmasv/masv-engine:3.2.15

• -v ~/masv-engine:/config maps the host directory to the container’s config directory. MASV Engine uses this to store configuration and transfer state. Keeping this data intact maintains transfer progress between restarts.
• -v ~/masv-files:/data maps the host directory to the container’s data directory, used for downloads and uploads.
• -u 1000:1000 sets the user and group ID that MASV Engine runs as. Replace with the appropriate IDs for your environment if needed.

Docker Compose

To authenticate with Docker Compose, define a Docker environment variable or Docker secret. This example uses an environment variable API_KEY:

version: "3"
services:
  masvengine:
    image: getmasv/masv-engine:3.2.15
    container_name: masv-engine
    user: "1000:1000"
    # Store your API key in a .env file — never commit it to version control.
    # See /api/api-keys/ for key management best practices.
    environment:
      - TZ=UTC
      - API_KEY=${API_KEY}
    volumes:
      - ~/masv-engine:/config
      - ~/masv-files:/data
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
    command: ["--api-key", "$API_KEY"]

Start the container:

docker-compose up

Caution

Never commit .env files to version control. Add .env to your .gitignore to prevent accidentally pushing secrets to your repository.

Parameters

When launching MASV Engine with masv server start, you can configure it using command-line flags. See the full list in the Getting Started guide.

Executing commands

Prefix any masv command with docker exec masv-engine to run it inside the container:

docker exec masv-engine masv gateway ls

For convenience, set up a shell alias to streamline interactions:

alias masv='docker exec masv-engine masv'

masv gateway ls

Alternatively, open an interactive shell inside the container:

docker exec -i masv-engine bash
masv gateway ls

Updating MASV Engine

Filesystem changes within a Docker container are not easily migrated to a new container. Store your configuration files in an external, persistent host directory (as described in Volume configuration) and follow these steps to update:

1. Stop the current MASV Engine container.

2. Back up the existing config directory (~/masv-engine) to a safe location. It contains configuration, transfer records, and any custom files such as scripts.

3. Pull the new MASV Engine image:

   docker pull getmasv/masv-engine:3.2.15

4. Point the new container to the existing config directory, or set up a new config directory and copy the old config files into it.

5. Start the new container.

6. Verify the new container is working as expected and records have been updated correctly.

7. Remove the old container.

Note

You can use the backed-up config directory to reinstall the previous version of MASV Engine if there are issues with an update. Delete the backup when you no longer need it.

Next steps

• Authentication — Authenticate with API keys or credentials before transferring files.
• Uploads — Send files via Team email, shareable Link, or Portal.
• Downloads — Initiate, monitor, and manage file downloads.
• Storage Gateway — Connect cloud storage providers to MASV.