Stay organized with collections
Save and categorize content based on your preferences.
Transfer agents transfer data from your file system to Google Cloud. You
can control agent options when you run an
agent through the flags and options described in this page.
Specifies one or more
volumes to
map from the host to the container. When using -v, we require
the host-directory
and container-directory to be the same, otherwise
Storage Transfer Service won't successfully locate your files for transfer.
Specifies an environment variable for the Docker container. Use this flag to
configure your agents to use a forward proxy. For more information, see
Using a forward proxy.
Agent options
--agent-id-prefix=id-prefix
An optional prefix that is prepended to the agent ID to help identify the
agent or its machine in the Google Cloud console. When a prefix is used, the
agent ID is formatted as prefix + hostname + Docker container ID.
--creds-file=credential-file
An optional JSON-formatted service account credential file. For more
information about generating a service account credential file, see
creating and managing service account keys.
--enable_mount_directory
Optionally mounts the whole file system under the directory
/transfer_root within the Docker container, rather than
specifying individual
Docker -vvolume mounts.
When using this flag, you don't need to prefix /transfer_root
to the log directory or the service account credentials file path, and
/transfer_root isn't visible in transfer logs or GUI error
samples.
--help
Displays brief usage help.
--hostname=hostname
set the hostname that the agent is running on. Used to report the hostname
of the machine a particular agent is running on.
--log-dir=logs-directory
An optional directory that the agent writes logs to. The default directory
is /tmp/.
--max-physical-mem=maximum-memory
Agents default to using 8GiB maximum of system memory. If the default
doesn't fit your environment, you can specify a relevant maximum memory
usage in the following formats:
max-physical-mem value
Maximum memory setting
6g
6 gigabytes
6gb
6 gigabytes
6GiB
6 gibibytes
--project-id=project-id
Required string of the project ID that is hosting the transfer resources that are created and billed.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Transfer agent command-line options\n\nTransfer agents transfer data from your file system to Google Cloud. You\ncan control agent options when you run an\nagent through the flags and options described in this page.\n\nCommand summary\n---------------\n\n```\nsudo docker run [--ulimit memlock=64000000 -d --rm -v host-directory:container-directory]\n--env environment-variable=variable-value\ngcr.io/cloud-ingest/tsop-agent:latest\n{--help | --version | --project-id=project-id}\n[--agent-id-prefix=id-prefix --creds-file=credential-file\n--enable_mount_directory --hostname=hostname\n--log-dir=logs-directory\n--max-physical-mem=maximum-memory]\n```\n\nDocker options\n--------------\n\n`--ulimit memlock=64000000`\n: Locks shared memory for a shared pool for Docker, so that it is always in\n memory for access by multiple sessions.\n\n`-d`\n\n: Starts the Docker container in detached mode, or in the background. This\n allows you to continue issuing commands from the Linux terminal.\n\n For more information, see\n [Detached -d](https://docs.docker.com/engine/reference/run/#detached--d)\n\n`--rm`\n\n: Deletes the container and the container's file system when Docker exits.\n\n For more information, see\n [Clean up (--rm)](https://docs.docker.com/engine/reference/run/#clean-up---rm)\n\n`-v `\u003cvar translate=\"no\"\u003ehost-directory\u003c/var\u003e`:`\u003cvar translate=\"no\"\u003econtainer-directory\u003c/var\u003e\n\n: Specifies one or more\n [volumes](https://docs.docker.com/storage/volumes/) to\n map from the host to the container. When using `-v`, we require\n the \u003cvar translate=\"no\"\u003ehost-directory\u003c/var\u003e\n and \u003cvar translate=\"no\"\u003econtainer-directory\u003c/var\u003e to be the same, otherwise\n Storage Transfer Service won't successfully locate your files for transfer.\n\n For more information, see\n [VOLUME (shared file systems)](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems)\n\n`--env `\u003cvar translate=\"no\"\u003eenvironment-variable\u003c/var\u003e`=`\u003cvar translate=\"no\"\u003evariable-value\u003c/var\u003e\n\n: Specifies an environment variable for the Docker container. Use this flag to\n configure your agents to use a forward proxy. For more information, see\n [Using a forward proxy](/storage-transfer/docs/on-prem-agent-details#using-forward-proxy).\n\nAgent options\n-------------\n\n`--agent-id-prefix=`\u003cvar translate=\"no\"\u003eid-prefix\u003c/var\u003e\n: An optional prefix that is prepended to the agent ID to help identify the\n agent or its machine in the Google Cloud console. When a prefix is used, the\n agent ID is formatted as `prefix + hostname + Docker container ID`.\n\n`--creds-file=`\u003cvar translate=\"no\"\u003ecredential-file\u003c/var\u003e\n\n: An optional JSON-formatted service account credential file. For more\n information about generating a service account credential file, see\n [creating and managing service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).\n\n | **Note:** Unless you are using `--enable_mount_directory`, you must prefix this path with `/transfer_root`, for example `/transfer_root/path/to/cred_file.json`.\n\n`--enable_mount_directory`\n\n: Optionally mounts the whole file system under the directory\n `/transfer_root` within the Docker container, rather than\n specifying individual\n [Docker `-v`volume mounts](https://docs.docker.com/storage/volumes/).\n When using this flag, you don't need to prefix `/transfer_root`\n to the log directory or the service account credentials file path, and\n `/transfer_root` isn't visible in transfer logs or GUI error\n samples.\n\n`--help`\n\n: Displays brief usage help.\n\n`--hostname=`\u003cvar translate=\"no\"\u003ehostname\u003c/var\u003e\n\n: set the hostname that the agent is running on. Used to report the hostname\n of the machine a particular agent is running on.\n\n | **Note:** We recommend passing `--hostname=$(hostname)` when using this flag.\n\n`--log-dir=`\u003cvar translate=\"no\"\u003elogs-directory\u003c/var\u003e\n\n: An optional directory that the agent writes logs to. The default directory\n is `/tmp/`.\n\n | **Note:** Unless you are using `--enable_mount_directory`, you must prefix this path with `/transfer_root`, for example, `/transfer/root/path/to/log_file`.\n\n`--max-physical-mem=`\u003cvar translate=\"no\"\u003emaximum-memory\u003c/var\u003e\n\n: Agents default to using 8GiB maximum of system memory. If the default\n doesn't fit your environment, you can specify a relevant maximum memory\n usage in the following formats:\n\n`--project-id=`\u003cvar translate=\"no\"\u003eproject-id\u003c/var\u003e\n\n: Required string of the project ID that is hosting the transfer resources that are created and billed.\n\n`--version`\n\n: Displays the current version of the agent."]]
