How to Upload and Download Files in a MicroVM

Last verified 16 Nov 2026

DigitalOcean MicroVMs are lightweight virtual machines that run a container image in an isolated kernel, pause automatically when idle, and resume on the next request with memory, files, and processes intact.

You can copy a single file into or out of a DigitalOcean MicroVM’s workload container using doctl or the API. Use file transfer to push a configuration file, seed data, or a build artifact into a running MicroVM, or to pull out logs and results, without rebuilding the image.

Each transfer moves one regular file of up to 64 MiB. An upload replaces the file at the destination path atomically, so your application never sees a partly written file. Every transfer reports the file’s SHA-256 checksum so you can confirm the content arrived intact.

If the MicroVM is paused, a transfer resumes it, and billing for compute resumes. If auto-resume is off, resume the MicroVM first.

Prerequisites

  • An account that is not in a free trial.
  • A personal access token with the microvm:update scope. Both uploads and downloads need this scope, because a downloaded file can contain secrets.
  • For doctl, doctl v2.0.1 or later.
  • For uploads, the destination’s parent directory must already exist in the container. To create it, run a command such as mkdir -p /app/config.

Transfer Files Using doctl

To upload a file, run doctl compute microvm upload with the local file and an absolute destination path in the container:

doctl compute microvm upload <your-microvm-id> \
  --local-file ./config.json \
  --path /app/config.json

The command prints the file’s path, size, SHA-256 checksum, mode, and owner in the container. By default, the file gets mode 0644 and is owned by the container’s user. To change these, add --mode, such as --mode 0600, or add --uid and --gid together.

To download a file, run doctl compute microvm download with the path in the container and a local path to save to:

doctl compute microvm download <your-microvm-id> \
  --path /var/log/app.log \
  --save-to ./app.log

doctl checks the downloaded content against the checksum the MicroVM sends. If the local file already exists, doctl overwrites it.

Transfer Files Using the API

To upload a file, send a PUT request to /v2/microvms/<your-microvm-id>/files with the destination path in the path query parameter and the raw file content as the request body:

curl -X PUT \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @config.json \
  "https://api.digitalocean.com/v2/microvms/<your-microvm-id>/files?path=/app/config.json"

The request must include a Content-Length header. curl sets it for you with --data-binary. The upload accepts the following optional query parameters:

  • mode: Octal permission bits, from 0001 to 0777. Defaults to 0644. Special bits, such as the setuid, setgid, and sticky bits, are rejected.
  • uid and gid: The file’s owner. Set both or neither. Defaults to the container’s user.
  • sha256: The lowercase hex SHA-256 of the body. If the content does not match, the upload fails and the existing file is left unchanged.

A successful upload returns HTTP 200 with the file’s path, size_bytes, sha256, mode, uid, and gid. The X-Checksum-Sha256 response header repeats the checksum.

To download a file, send a GET request to the same endpoint:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -o app.log \
  -D - \
  "https://api.digitalocean.com/v2/microvms/<your-microvm-id>/files?path=/var/log/app.log"

The response body is the raw file content. The X-Checksum-Sha256 response header contains the file’s SHA-256 checksum. Compare it with the checksum of the file you saved, for example with sha256sum app.log.

Errors

Both directions return the following errors:

Status Meaning
400 The path is missing, relative, or not clean, such as a path containing .. or a trailing /. A query parameter is malformed, or the upload body ended early. Also returned while the MicroVM is provisioning.
403 The token does not have the microvm:update scope, file transfer is not available for your team, or the container user cannot read or write the file.
404 The MicroVM does not exist, or the file or its parent directory does not exist in the container.
409 The workload is not running, the path is a directory or another file type that is not a regular file, or the MicroVM is too old to support file transfer. To use file transfer on an older MicroVM, create a new MicroVM.
411 The upload has no Content-Length header.
413 The file is larger than 64 MiB, or the container’s disk is full.
422 The uploaded content does not match the sha256 you sent.
429 The MicroVM is already serving four downloads, or the service is busy. Retry after a short delay.
504 The transfer did not finish within 10 minutes.

An upload does not follow or replace a symbolic link at the destination path. Upload to the file the link points to instead.

To move a whole directory, archive it first, then transfer the archive. For example, run tar czf /tmp/data.tgz /app/data with doctl compute microvm exec, then download /tmp/data.tgz.

For other limits, see MicroVMs Limits.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.