Setup: Docker

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

Supported architectures

MASV Agent supports multiple architectures for deployment in various environments. Use the masvio/masv-agent:latest image tag to automatically pull the correct architecture for your system.

Architecture	Tag
x86-64	latest
arm64	latest

Pulling the image

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

docker pull masvio/masv-agent:latest

Volume configuration

MASV Agent 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-agent
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-agent \
  -u 1000:1000 \
  -v ~/masv-agent:/config \
  -v ~/masv-files:/data \
  --restart unless-stopped \
  masvio/masv-agent:latest

• -v ~/masv-agent:/config maps the host directory to the container’s config directory. MASV Agent 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 Agent 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:
  masvagent:
    image: masvio/masv-agent:latest
    container_name: masv-agent
    user: "1000:1000"
    environment:
      - TZ=UTC
      - API_KEY=${API_KEY}
    volumes:
      - ~/masv-agent:/config
      - ~/masv-files:/data
    ports:
      - 8080:8080
    restart: unless-stopped
    command: ["--api-key", "$API_KEY"]

Start the container:

docker-compose up

Parameters

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

Executing commands

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

docker exec masv-agent masv gateway ls

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

alias masv='docker exec masv-agent masv'

masv gateway ls

Alternatively, open an interactive shell inside the container:

docker exec -i masv-agent bash
$ masv gateway ls

Updating MASV Agent

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 Agent container.
2. Back up the existing config directory (~/masv-agent) to a safe location. It contains configuration, transfer records, and any custom files such as scripts.
3. Pull the new MASV Agent image:

   docker pull masvio/masv-agent:latest

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 Agent 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.