MASV Agent-based automation

In this tutorial, you’ll use the MASV Agent, a cross-platform headless service that runs on your server, workstation, or NAS device, to automate transfers. The MASV Agent 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 Agent
• Authenticate
• Send files to a portal
• Monitor transfer status
• Manage in-progress transfers
• Download files

Architecture overview

[Your server / NAS / pipeline host]
  │
  │  MASV Agent 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 Agent 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 Web App.
• Identify the portals or individuals/team you want to send to.

Step 1: Start the MASV Agent server

Start the MASV Agent’s 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 Agent 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 Agent 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 Agent 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 Agent 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 Agent stores transfer state locally in $HOME/.masvsrv. If you redeploy the MASV Agent 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 Agent is available as a container image. When running in Docker, ensure the paths you pass to the MASV Agent 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 Agent 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.