MASV Engine automation

In this tutorial, you’ll use the MASV Engine (formerly MASV Agent), a cross-platform headless service that runs on your server, workstation, or NAS device, to automate transfers. The MASV Engine manages upload and download transfers locally, handling chunking, retries, and automatic transfer resume. You control it through a CLI or its local REST API — making it easy to execute from shell scripts, orchestration tools, or any language that can make HTTP calls to localhost.

What you’ll learn

In this tutorial, you will:

• Start the MASV Engine
• Authenticate
• Send files to a portal
• Monitor transfer status
• Manage in-progress transfers
• Download files

Architecture overview

[Your server / NAS / pipeline host]
  │
  │  MASV Engine runs as a persistent local service.
  │
  ├── masv server start --api-key="$MASV_API_KEY"
  │
  │  Your application or script issues commands:
  │   via CLI:        masv upload start portal ...
  │   via local REST: POST http://localhost:8080/api/v1/portals/uploads
  │
[MASV Cloud]
  │
  │  Transfer completes; webhook is triggered (optional).
  │
[Downstream system]

Before you begin

• Install MASV Engine on your host. It is available as a native binary for Windows, macOS, and Linux, or as a Docker container image.
• Generate an API key in the MASV Admin Console.
• Identify the portals or individuals/team you want to send to.

Step 1: Start the MASV Engine server

Start the MASV Engine local server, providing your API key at startup:

# Store your API key in an environment variable — never hardcode it.
export MASV_API_KEY="your-key-here"
masv server start --api-key="$MASV_API_KEY"

The server starts listening at http://localhost:8080 by default. All subsequent MASV Engine commands communicate with this local server.

Useful startup flags:

Flag	Purpose
--auto-finalize=true	Automatically finalizes uploads after all files are transferred (default: true).
--auto-resume=true	Resumes in-progress transfers after a restart (default: true).
--chunk-size=100MB	Sets the default chunk size for all transfers.
--listen=http://localhost:8080	Changes the listen address if the default port is unavailable.

For production deployments, configure the MASV Engine to start on system boot using your platform’s service manager (systemd, launchd, or Windows Services).

Step 2: Authenticate (for team uploads)

Portal uploads do not require a user session — you can send uploads to any portal without logging in. Individual and team uploads (packages sent to email recipients or shared via a link) require a user session:

masv user login --email "$MASV_EMAIL" --password "$MASV_PASSWORD"

For automation, pass the API key at server start instead (recommended):

masv server start --api-key="$MASV_API_KEY"

Step 3: Send files to a portal

Using the CLI:

masv upload start portal \
  --subdomain=your-portal-subdomain \
  --sender='pipeline@yourcompany.com' \
  --name="Dailies - 2026-06-10" \
  --description="Camera A rushes" \
  /mnt/storage/project/dailies/

Using the local REST API:

curl -X POST \
  -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/portals/uploads \
  -d '{
    "subdomain": "your-portal-subdomain",
    "sender_email": "pipeline@yourcompany.com",
    "package_name": "Dailies - 2026-06-10",
    "paths": ["/mnt/storage/project/dailies/"],
    "package_description": "Camera A rushes"
  }'

The response includes an upload ID you can use to monitor progress.

Step 4: Monitor transfer status

Using the CLI:

masv upload ls                    # list all uploads
masv upload status UPLOAD_ID      # full details including per-file state

Using the local REST API:

curl http://localhost:8080/api/v1/uploads/{UPLOAD_ID}

Upload states to watch for:

State	Meaning
transferring	Files are actively being sent.
idle	All bytes uploaded; awaiting finalization.
complete	Package finalized and recipient notified.
error	A fatal error occurred.
paused	Transfer was paused.

Step 5: Manage in-progress transfers

You can pause, resume, or cancel transfers at any time:

masv upload pause UPLOAD_ID
masv upload resume UPLOAD_ID
masv upload rm UPLOAD_ID

Step 6: Download files (for receive workflows)

MASV Engine also handles downloads, making it straightforward to build automation around receiving file packages:

# Start a download from a download link
masv download start LINK_ID --secret LINK_SECRET --destination /mnt/ingest/

Or via local REST:

curl -X POST \
  -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/downloads \
  -d '{
    "link_id": "LINK_ID",
    "secret": "LINK_SECRET",
    "destination_path": "/mnt/ingest/"
  }'

Production considerations

• Auto-finalize behavior: By default, the MASV Engine finalizes uploads automatically when all bytes are transferred. If your workflow includes adding files to a package incrementally — for example, a render job that produces files over time — disable auto-finalize at startup (--auto-finalize=false) and finalize explicitly when the package is ready.
• State persistence: The MASV Engine stores transfer state locally in $HOME/.masvsrv. If you redeploy the MASV Engine or move it to a new host, transfer history does not carry over. Use --config-dir to point to persistent storage if needed.
• Docker deployments: The MASV Engine is available as a container image. When running in Docker, ensure the paths you pass to the MASV Engine are paths inside the container’s filesystem, and mount your host storage as volumes accordingly.
• Storage Gateway: For NAS and on-premises storage environments, MASV Engine supports a Storage Gateway mode that exposes your connected storage to MASV Portals, enabling automatic file delivery to physical storage without requiring your team to have direct network access to the device.