Getting Started with MASV Agent

MASV Agent is a cross-platform service that manages file transfers to and from the MASV network. It functions as a CLI tool backed by a local REST API server that you can also call directly.

The Agent supports simultaneous upload and download of multiple Packages, handles file system interactions, and is stateful — it stores transfer metadata and user sessions to survive interruptions and shutdowns. MASV Agent is used to transfer terabytes of data every day, reliably and quickly.

Before installing, check the MASV Agent System Requirements. For the latest changes, see the MASV Agent Release Notes.

Installation

You can install MASV Agent as a native binary or run it with Docker.

Native binary (recommended)

The recommended way to run MASV Agent is to install it natively on your operating system:

• Linux — Install via .deb or .rpm package on Ubuntu, Debian, CentOS, or other Linux distributions.
• macOS — Install on macOS using the provided installer.
• Windows — Install on Windows using the MSI installer.

Docker

MASV Agent is also available as a Docker container image, making it easy to run across different operating systems and architectures. See the Docker setup guide for image pull, volume configuration, container startup, and updating instructions.

Starting the server

To use MASV Agent, start the local server first:

masv server start

The server accepts several configuration flags:

Flag	Type	Default	Description
api-key	String	—	MASV API key for authentication
auto-finalize	Boolean	true	Automatically finalize uploads when they reach 100% progress
auto-resume	Boolean	true	Automatically resume transfers when the server starts
chunk-size	String	100MB	Target chunk size for uploads and downloads, formatted as {number}{unit}
config-dir	String	$HOME/.masvsrv	Storage location for configuration files and the database
listen	String	http://localhost:8080	Listen address and port (port 0 for system-assigned)
log-format	String	[%lvl%] %time%: %msg%	Log format string
log-level	String	debug	Log level: debug, info, warning, error
log-out	String	stdout	Log output destination: stdout, stderr, or a filename
log-timestamp-format	String	15:04:05	Timestamp format for log entries
memory-cache	Boolean	true	Use RAM to boost transfer performance
transfer-cleanup-days	Integer	—	Automatically delete transfers older than this many days from local history (minimum 1)
version	—	—	Display the current version and available updates

Once the server is running, you can use the rest of the MASV Agent commands.

Basic commands

List all available commands and flags:

masv -h

Check which version of MASV Agent is installed:

masv version

Gracefully stop the local server:

masv server shutdown

Viewing logs

The MASV Agent log helps you review activity and troubleshoot issues.

Platform	How to view logs
Docker	Run docker container ls to get the container ID, then docker logs <container_id>
Linux	Run journalctl -u masv-agent to view systemd log output
macOS	Open $HOME/masv-agent/main.log
Windows	Open Event Viewer → Windows Logs → Application, and filter by source masv-agent

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.
• Automations — Set up watch folders, Portal downloads, and stream uploads.
• Storage Gateway — Connect cloud storage providers to MASV.
• CLI Reference — Complete list of all Agent commands and parameters.
• Settings — Configure disk, FIFO mode, multiconnect, and rate-limit options.