Back to Details

companion-clis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Companion CLIs

配套CLI工具

Four CLIs commonly needed alongside Runpod: HuggingFace (
hf
), GitHub (
gh
), Docker (
docker
), and AWS (
aws
). Each requires credentials before use.
Runpod 工作流中常用的四款 CLI 工具：HuggingFace（
hf
）、GitHub（
gh
）、Docker（
docker
）和 AWS（
aws
）。使用前均需配置凭证。

Windows: Install WSL2 First

Windows 用户：先安装 WSL2

If you are on Windows, install WSL2 (Windows Subsystem for Linux) before proceeding. WSL2 gives you a native Linux environment on Windows, which all these CLIs are designed for. Run in PowerShell as Administrator, then restart:
powershell
wsl --install
This installs WSL2 with Ubuntu by default. After restarting, open the Ubuntu app to complete setup (create a Linux username and password). From that point on, follow the Linux instructions throughout this skill.
如果使用 Windows 系统，请先安装 WSL2（Windows Subsystem for Linux，Windows 子系统 Linux）再继续操作。WSL2 可为 Windows 提供原生 Linux 环境，而这些 CLI 工具均基于该环境设计。以管理员身份运行 PowerShell，执行以下命令后重启系统：
powershell
wsl --install
该命令默认安装带 Ubuntu 的 WSL2。重启后打开 Ubuntu 应用完成设置（创建 Linux 用户名和密码）。此后全程遵循 Linux 操作说明即可。

HuggingFace CLI

HuggingFace CLI

The HuggingFace CLI (
hf
) is used to download models from the Hub to your local machine so they are cached and available when you build and run the Docker container. For example, to deploy 
meta-llama/Llama-3.1-8B
to a Runpod serverless endpoint: download the model locally first, build a Docker image that includes or mounts it, validate the container locally, then push the image to Docker Hub for Runpod to pull.
HuggingFace CLI（
hf
）用于从 HuggingFace Hub 下载模型到本地机器，以便缓存模型，在构建和运行 Docker 容器时直接调用。例如，要将 
meta-llama/Llama-3.1-8B
部署到 Runpod 无服务器端点：需先在本地下载模型，构建包含或挂载该模型的 Docker 镜像，在本地验证容器，再将镜像推送到 Docker Hub 供 Runpod 拉取。

Install

安装

bash
undefined
bash
undefined

macOS / Linux (standalone installer — recommended)

macOS / Linux（独立安装程序 —— 推荐）

curl -LsSf https://hf.co/cli/install.sh | bash
curl -LsSf https://hf.co/cli/install.sh | bash

macOS (Homebrew)

macOS（Homebrew）

brew install hf
brew install hf

Windows (WSL2): use the Linux standalone installer above

Windows（WSL2）：使用上述 Linux 独立安装程序


> **Note:** `pip install huggingface_hub` installs the older Python CLI (`huggingface-cli`), which uses different command syntax. The commands below are for the standalone `hf` CLI.

> **注意**：`pip install huggingface_hub` 安装的是旧版 Python CLI（`huggingface-cli`），其命令语法不同。以下命令适用于独立版 `hf` CLI。

Credentials

凭证配置

Get a token at https://huggingface.co/settings/tokens. Use write access for uploading; read access is sufficient for downloading public or gated models.
bash
undefined
访问 https://huggingface.co/settings/tokens 获取令牌。上传模型需写入权限；下载公开或 gated 模型仅需读取权限。
bash
undefined

Option 1: interactive login (saves token to ~/.cache/huggingface/token, optionally to git credential store)

方式1：交互式登录（将令牌保存到 ~/.cache/huggingface/token，可选保存到 git 凭证存储）

hf auth login
hf auth login

Option 2: non-interactive (pass token directly, useful in scripts and pod start commands)

方式2：非交互式登录（直接传入令牌，适用于脚本和 Pod 启动命令）

hf auth login --token $HF_TOKEN --add-to-git-credential
hf auth login --token $HF_TOKEN --add-to-git-credential

Option 3: environment variable (takes precedence over saved token; to revert, unset the variable)

方式3：环境变量（优先级高于已保存的令牌；如需恢复，取消设置该变量）

export HF_TOKEN=hf_...

```bash
hf auth whoami      # confirm auth and org memberships
hf auth logout      # delete all locally stored tokens
export HF_TOKEN=hf_...

```bash
hf auth whoami      # 确认认证状态及组织成员身份
hf auth logout      # 删除所有本地存储的令牌

Key Commands

核心命令

bash
undefined
bash
undefined

Download a model to a local directory (use --local-dir to control where it lands)

将模型下载到本地目录（使用 --local-dir 指定存储路径）

hf download meta-llama/Llama-3.1-8B --local-dir ./models/llama-3.1-8b hf download TinyLlama/TinyLlama-1.1B-Chat-v1.0 --local-dir ./models/tinyllama
hf download meta-llama/Llama-3.1-8B --local-dir ./models/llama-3.1-8b hf download TinyLlama/TinyLlama-1.1B-Chat-v1.0 --local-dir ./models/tinyllama

Download a single file from a model repo

从模型仓库下载单个文件

hf download meta-llama/Llama-3.1-8B config.json --local-dir ./models/llama-3.1-8b
hf download meta-llama/Llama-3.1-8B config.json --local-dir ./models/llama-3.1-8b

Download with glob filters (e.g. only safetensors weights, skip fp16 variants)

使用通配符过滤下载（例如仅下载 safetensors 权重，跳过 fp16 变体）

hf download stabilityai/stable-diffusion-xl-base-1.0
--include ".safetensors" --exclude ".fp16.*"
--local-dir ./models/sdxl
hf download stabilityai/stable-diffusion-xl-base-1.0
--include ".safetensors" --exclude ".fp16.*"
--local-dir ./models/sdxl

Download a specific revision (commit hash, branch, or tag — append --revision REF)

下载特定版本（提交哈希、分支或标签 —— 添加 --revision REF 参数）

hf download meta-llama/Llama-3.1-8B --revision v1.0 --local-dir ./models/llama-3.1-8b
undefined
hf download meta-llama/Llama-3.1-8B --revision v1.0 --local-dir ./models/llama-3.1-8b
undefined

Troubleshooting

故障排查

bash
undefined
bash
undefined

Increase download timeout on slow connections (default: 10s)

在慢速网络下增加下载超时时间（默认：10秒）

export HF_HUB_DOWNLOAD_TIMEOUT=30

---
export HF_HUB_DOWNLOAD_TIMEOUT=30

---

GitHub CLI

GitHub CLI

The GitHub CLI (
gh
) is used to manage repositories for Runpod serverless workers. This includes cloning repos into local Docker containers for testing, versioning source code so changes can be tracked and shared with teammates or collaborators, and creating GitHub releases that publish listings to the Runpod Hub. The Hub indexes releases — not commits — so every deployment update requires a new release.
GitHub CLI（
gh
）用于管理 Runpod 无服务器 Worker 的代码仓库。包括将仓库克隆到本地 Docker 容器进行测试、对源代码进行版本控制以便跟踪变更并与团队成员共享、创建 GitHub Release 并发布到 Runpod Hub。Runpod Hub 索引的是 Release 而非提交记录，因此每次部署更新都需要创建新的 Release。

Install

安装

bash
undefined
bash
undefined

macOS

macOS

brew install gh
brew install gh

Linux (Debian/Ubuntu)

Linux（Debian/Ubuntu）

(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y))
&& sudo mkdir -p -m 755 /etc/apt/keyrings
&& out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg
&& cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main"
| sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
&& sudo apt update && sudo apt install gh -y
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y))
&& sudo mkdir -p -m 755 /etc/apt/keyrings
&& out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg
&& cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main"
| sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
&& sudo apt update && sudo apt install gh -y

Linux (Alpine)

Linux（Alpine）

apk add github-cli
apk add github-cli

Windows (WSL2): use the Linux (Debian/Ubuntu) installer above

Windows（WSL2）：使用上述 Linux（Debian/Ubuntu）安装程序

undefined
undefined

SSH Keys

SSH 密钥

An SSH key identifies your machine as authentic to remote services. Generate one key and register the public key with each service that requires it — GitHub (via 
gh
) and HuggingFace (via browser).
Generate a key
bash
ssh-keygen -t ed25519 -C "your_email@example.com"
SSH 密钥用于验证机器对远程服务的身份。生成一对密钥后，将公钥注册到每个需要的服务中——GitHub（通过 
gh
）和 HuggingFace（通过浏览器）。
生成密钥
bash
ssh-keygen -t ed25519 -C "your_email@example.com"

Saves to ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public)

密钥将保存到 ~/.ssh/id_ed25519（私钥）和 ~/.ssh/id_ed25519.pub（公钥）

Press Enter to accept the default path; set a passphrase or leave blank

按回车键接受默认路径；可设置密码短语或留空


**Add the key to the SSH agent**

```bash

**将密钥添加到 SSH 代理**

```bash

macOS

macOS

eval "$(ssh-agent -s)" ssh-add --apple-use-keychain ~/.ssh/id_ed25519
eval "$(ssh-agent -s)" ssh-add --apple-use-keychain ~/.ssh/id_ed25519

macOS — also add to ~/.ssh/config so the key loads automatically on login.

macOS —— 同时将配置添加到 ~/.ssh/config，以便登录时自动加载密钥

Create the file if it doesn't exist, and add these lines:

若文件不存在则创建，添加以下内容：

Host *

Host *

AddKeysToAgent yes

AddKeysToAgent yes

UseKeychain yes

UseKeychain yes

IdentityFile ~/.ssh/id_ed25519

IdentityFile ~/.ssh/id_ed25519

Linux

Linux

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519

Windows (WSL2): use the Linux instructions above

Windows（WSL2）：使用上述 Linux 操作说明

undefined
undefined

Credentials

凭证配置

bash
undefined
bash
undefined

Interactive login — when prompted, select SSH as the git protocol

交互式登录 —— 提示时选择 SSH 作为 git 协议

gh auth login
gh auth login

Verify auth

验证认证状态

gh auth status

**Register the public key with each service**

```bash
gh auth status

**将公钥注册到各服务**

```bash

GitHub — upload via gh CLI (requires auth above to be completed first)

GitHub —— 通过 gh CLI 上传（需先完成上述认证）

gh ssh-key add ~/.ssh/id_ed25519.pub --title "my-machine"
gh ssh-key add ~/.ssh/id_ed25519.pub --title "my-machine"

HuggingFace — paste contents of public key manually in browser

HuggingFace —— 在浏览器中手动粘贴公钥内容

cat ~/.ssh/id_ed25519.pub # copy this output
cat ~/.ssh/id_ed25519.pub # 复制该输出

Then add at https://huggingface.co/settings/keys

然后访问 https://huggingface.co/settings/keys 添加

undefined
undefined

Key Commands

核心命令

bash
undefined
bash
undefined

Repositories

仓库操作

gh repo create my-worker --public # create a new public repo (required for Hub) gh repo clone owner/repo # clone a repository over SSH gh repo clone owner/repo -- --depth 1 # shallow clone gh repo view owner/repo # view repo details and URL
gh repo create my-worker --public # 创建新的公开仓库（Hub 要求） gh repo clone owner/repo # 通过 SSH 克隆仓库 gh repo clone owner/repo -- --depth 1 # 浅克隆 gh repo view owner/repo # 查看仓库详情和 URL

Releases — the Runpod Hub indexes releases, not commits

Release 操作 —— Runpod Hub 索引的是 Release，而非提交记录

Every update to a Hub listing requires a new GitHub release

每次更新 Hub 列表都需要创建新的 GitHub Release

gh release create v1.0.0 --title "v1.0.0" --notes "Initial release" # create a release gh release create v1.0.1 --title "v1.0.1" --notes "Update model tag" # update Hub listing gh release list # list all releases gh release view v1.0.0 # view release details
undefined
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release" # 创建 Release gh release create v1.0.1 --title "v1.0.1" --notes "Update model tag" # 更新 Hub 列表 gh release list # 列出所有 Release gh release view v1.0.0 # 查看 Release 详情
undefined

Runpod Hub repository structure

Runpod Hub 仓库结构

A Hub-compatible repository requires these files (in root or 
.runpod/
directory):
handler.py        # serverless worker implementation
Dockerfile        # container definition
README.md         # documentation shown on Hub listing
.runpod/
  hub.json        # Hub metadata: title, description, category, GPU config, env vars
  tests.json      # test cases run after each release
To publish: go to https://console.runpod.io → Hub → Add your repo → enter the GitHub repository URL.
兼容 Hub 的仓库需包含以下文件（位于根目录或 
.runpod/
目录）：
handler.py        # 无服务器 Worker 实现代码
Dockerfile        # 容器定义文件
README.md         # Hub 列表展示的文档
.runpod/
  hub.json        # Hub 元数据：标题、描述、分类、GPU 配置、环境变量
  tests.json      # 每次 Release 后运行的测试用例
发布流程：访问 https://console.runpod.io → Hub → Add your repo → 输入 GitHub 仓库 URL。

Docker

Docker

Docker is used to build and validate container images locally before pushing to Docker Hub. Runpod uses Docker Hub as its default image registry — serverless endpoints, pods, and templates all reference images by their Docker Hub tag. Once an image is pushed, Runpod workers pull it automatically when the endpoint or pod is started.
Docker 用于在本地构建和验证容器镜像，再推送到 Docker Hub。Runpod 默认使用 Docker Hub 作为镜像注册表——无服务器端点、Pod 和模板均通过 Docker Hub 标签引用镜像。镜像推送完成后，Runpod Worker 会在启动端点或 Pod 时自动拉取。

Install

安装

macOS: Download Docker Desktop from https://docs.docker.com/desktop/setup/install/mac-install/
  • Choose the Apple Silicon installer for M-series Macs, or Intel Chip for older Macs
  • Open the DMG, drag Docker to Applications, and launch it
Windows: Download Docker Desktop from https://docs.docker.com/desktop/setup/install/windows-install/
  • Requires WSL 2 — if you followed the WSL2 setup above, Docker Desktop will detect it automatically
  • After installation, 
    docker
    commands work inside your WSL2 terminal without extra configuration
  • Run the installer and follow the setup wizard
Linux: See https://docs.docker.com/engine/install/ for distro-specific instructions
bash
undefined
macOS：从 https://docs.docker.com/desktop/setup/install/mac-install/ 下载 Docker Desktop
  • M 系列 Mac 选择 Apple Silicon 安装包，旧款 Intel 芯片选择 Intel Chip 安装包
  • 打开 DMG 文件，将 Docker 拖到 Applications 文件夹，然后启动
Windows：从 https://docs.docker.com/desktop/setup/install/windows-install/ 下载 Docker Desktop
  • 需依赖 WSL 2 —— 若已完成上述 WSL2 设置，Docker Desktop 会自动检测
  • 安装完成后，在 WSL2 终端中可直接使用 
    docker
    命令，无需额外配置
  • 运行安装程序并遵循向导完成设置
Linux：查看 https://docs.docker.com/engine/install/ 获取发行版专属安装说明
bash
undefined

Linux convenience script (Ubuntu/Debian)

Linux 便捷脚本（Ubuntu/Debian）

curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # allow non-root usage (re-login after)
undefined
curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # 允许非 root 用户使用（需重新登录生效）
undefined

Credentials

凭证配置

Docker Hub authentication uses a personal access token (PAT), not your account password.
  1. Go to https://app.docker.com → Avatar (top right) → Account Settings → Personal Access Tokens
  2. Click Generate new token — give it a descriptive name, set an expiration, and choose Read & Write access
  3. Copy the token immediately — it is shown only once
bash
docker login -u DOCKERHUB_USERNAME
Docker Hub 认证使用个人访问令牌（PAT），而非账户密码。
  1. 访问 https://app.docker.com → 右上角头像 → Account Settings → Personal Access Tokens
  2. 点击 Generate new token —— 设置描述性名称、过期时间，并选择 Read & Write 权限
  3. 立即复制令牌 —— 仅显示一次
bash
docker login -u DOCKERHUB_USERNAME

When prompted for a password, paste your personal access token

提示输入密码时，粘贴个人访问令牌


Credentials are saved to `~/.docker/config.json` after a successful login.

认证成功后，凭证将保存到 `~/.docker/config.json`。

Tagging

镜像打标

Always use explicit semantic version tags. Never rely on 
latest
.
The 
latest
tag does not automatically point to the newest image — it only reflects the last build that was pushed without an explicit tag. If you push 
v1.0.0
and then push 
v1.0.1
with an explicit tag, 
latest
still points to 
v1.0.0
. Runpod workers pinned to 
latest
will silently pull the wrong version.
Use a tag that uniquely identifies the build: 
v1.0.0
, 
v1.0.1
, etc.
bash
undefined
始终使用明确的语义化版本标签。绝不要依赖 
latest
标签。
latest
标签不会自动指向最新镜像——它仅反映最后一次未指定明确标签推送的构建。若先推送 
v1.0.0
，再推送带明确标签的 
v1.0.1
，
latest
仍指向 
v1.0.0
。绑定到 
latest
的 Runpod Worker 会静默拉取错误版本。
使用唯一标识构建的标签：
v1.0.0
、
v1.0.1
等。
bash
undefined

Correct: explicit semantic version tag

正确做法：使用明确的语义化版本标签

docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . docker push myorg/myimage:v1.0.0
docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . docker push myorg/myimage:v1.0.0

Wrong: latest tag is ambiguous and unreliable

错误做法：latest 标签模糊且不可靠

docker build -t myorg/myimage:latest .
undefined
docker build -t myorg/myimage:latest .
undefined

Docker Hub

Docker Hub

Docker Hub is the registry Runpod pulls images from. After pushing, images are visible at https://hub.docker.com/repositories/ and referenceable in Runpod as 
username/image:tag
.
Images on Docker Hub can be public (anyone can pull) or private (requires credentials). For private images, register your Docker Hub credentials in Runpod once and they become available to any template:
  1. Go to https://console.runpod.io/user/settings → Container Registry Settings
  2. Add your Docker Hub username and personal access token (the same PAT used for 
    docker login
    )
  3. When creating or editing a template, select the saved credential from the dropdown
Runpod currently only supports 
docker login
type credentials for container registry authentication.
Docker Hub 是 Runpod 拉取镜像的注册表。推送完成后，镜像可在 https://hub.docker.com/repositories/ 查看，并可在 Runpod 中通过 
username/image:tag
引用。
Docker Hub 上的镜像可以是公开的（任何人可拉取）或私有（需凭证）。对于私有镜像，在 Runpod 中注册 Docker Hub 凭证一次后，所有模板均可使用：
  1. 访问 https://console.runpod.io/user/settings → Container Registry Settings
  2. 添加 Docker Hub 用户名和个人访问令牌（与 
    docker login
    使用的 PAT 相同）
  3. 创建或编辑模板时，从下拉菜单选择已保存的凭证
Runpod 目前仅支持 
docker login
类型的凭证用于容器注册表认证。

Key Commands

核心命令

bash
undefined
bash
undefined

Build for Runpod (always --platform=linux/amd64 — pods run on x86 Linux)

为 Runpod 构建镜像（始终添加 --platform=linux/amd64 —— Pod 运行在 x86 Linux 环境）

docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 -f Dockerfile.prod . # specify Dockerfile
docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 -f Dockerfile.prod . # 指定 Dockerfile

Tag an existing image before pushing (does not duplicate image data)

推送前为现有镜像打标（不会复制镜像数据）

docker tag myorg/myimage:v1.0.0 myorg/myimage:v1.0.1
docker tag myorg/myimage:v1.0.0 myorg/myimage:v1.0.1

Push to Docker Hub (image becomes available to Runpod as myorg/myimage:v1.0.0)

推送到 Docker Hub（镜像将可被 Runpod 以 myorg/myimage:v1.0.0 引用）

docker push myorg/myimage:v1.0.0
docker push myorg/myimage:v1.0.0

Run locally for validation

在本地运行以验证

docker run --rm -it myorg/myimage:v1.0.0 bash docker run --rm --gpus all myorg/myimage:v1.0.0 bash # with GPU (requires nvidia-container-toolkit) docker run --rm -p 8080:80 -e API_KEY=secret myorg/myimage:v1.0.0 # port mapping + env vars
docker run --rm -it myorg/myimage:v1.0.0 bash docker run --rm --gpus all myorg/myimage:v1.0.0 bash # 启用 GPU（需 nvidia-container-toolkit） docker run --rm -p 8080:80 -e API_KEY=secret myorg/myimage:v1.0.0 # 端口映射 + 环境变量

Debug a running container

调试运行中的容器

docker exec -it CONTAINER_ID /bin/bash
docker exec -it CONTAINER_ID /bin/bash

Inspect

检查操作

docker images # list local images docker ps -a # list all containers (including stopped) docker logs CONTAINER_ID # view container output docker logs -f CONTAINER_ID # follow logs in real time
docker images # 列出本地镜像 docker ps -a # 列出所有容器（包括已停止的） docker logs CONTAINER_ID # 查看容器输出 docker logs -f CONTAINER_ID # 实时跟踪日志

Cleanup

清理操作

docker rmi myorg/myimage:v1.0.0 # remove an image docker rm CONTAINER_ID # remove a stopped container

---
docker rmi myorg/myimage:v1.0.0 # 删除镜像 docker rm CONTAINER_ID # 删除已停止的容器

---

AWS CLI

AWS CLI

The AWS CLI is used to access Runpod storage over the S3 protocol. Any Runpod product that can mount a Network Volume — pods, clusters, and serverless endpoints — can have its storage accessed this way. The bucket name is the network volume ID.
AWS CLI 用于通过 S3 协议访问 Runpod 存储。任何可挂载网络卷的 Runpod 产品——Pod、集群和无服务器端点——都可通过此方式访问存储。存储桶名称即为网络卷 ID。

Install

安装

bash
undefined
bash
undefined

macOS

macOS

brew install awscli
brew install awscli

Linux

Linux

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip unzip awscliv2.zip && sudo ./aws/install
undefined
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip unzip awscliv2.zip && sudo ./aws/install
undefined

Credentials

凭证配置

Runpod uses its own S3-compatible API, not AWS. You need a Runpod user ID and S3 API key — not an AWS account.
  • Access key (
    AWS_ACCESS_KEY_ID
    ): your Runpod user ID — found in the console under Settings > S3 API Keys, in the key description (format: 
    user_...
    )
  • Secret key (
    AWS_SECRET_ACCESS_KEY
    ): an S3 API key — generate one at Settings > S3 API Keys > Create. Shown only once; save it immediately (format: 
    rps_...
    )
bash
undefined
Runpod 使用自有兼容 S3 的 API，而非 AWS 官方 API。需使用 Runpod 用户 ID 和 S3 API 密钥——无需 AWS 账户。
  • 访问密钥（
    AWS_ACCESS_KEY_ID
    ）：Runpod 用户 ID —— 在控制台 Settings > S3 API Keys 中查看，格式为 
    user_...
  • 密钥（
    AWS_SECRET_ACCESS_KEY
    ）：S3 API 密钥 —— 在 Settings > S3 API Keys > Create 生成。仅显示一次；需立即保存，格式为 
    rps_...
bash
undefined

Option 1: interactive configure (writes ~/.aws/credentials and ~/.aws/config)

方式1：交互式配置（写入 ~/.aws/credentials 和 ~/.aws/config）

When prompted: enter user ID as access key, S3 API key as secret.

提示时：输入用户 ID 作为访问密钥，输入 S3 API 密钥作为密钥

Press Enter to skip region and output format — region is always passed per-command, not stored in config.

按回车键跳过区域和输出格式设置——区域需在每个命令中指定，不存储在配置中

aws configure
aws configure list # verify stored credentials
aws configure
aws configure list # 验证已存储的凭证

Option 2: environment variables (override config files)

方式2：环境变量（覆盖配置文件）

export AWS_ACCESS_KEY_ID=user_... export AWS_SECRET_ACCESS_KEY=rps_...
export AWS_ACCESS_KEY_ID=user_... export AWS_SECRET_ACCESS_KEY=rps_...

To stop using env vars and fall back to config file:

停止使用环境变量并恢复为配置文件：

unset AWS_ACCESS_KEY_ID unset AWS_SECRET_ACCESS_KEY
undefined
unset AWS_ACCESS_KEY_ID unset AWS_SECRET_ACCESS_KEY
undefined

Region and Endpoint

区域和端点

The 
--region
flag on every command is the Runpod datacenter ID where the network volume lives — not an AWS region. The 
--endpoint-url
is derived from the same datacenter ID.
Every command requires both flags:
--region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/
Tip: Each network volume on the storage page at https://console.runpod.io/user/storage/ shows a pre-filled example 
aws s3 ls
command with the correct 
--region
and 
--endpoint-url
already substituted. Use this to confirm the exact values for a given volume.
Datacenter IDs by region:
RegionDatacenter IDs
EUCZ-1, RO-1, IS-1, NO-1
USCA-2, GA-2, IL-1, KS-2, MD-1, MO-1, MO-2, NC-1, NC-2, NE-1, WA-1
每个命令中的 
--region
标志是网络卷所在的 Runpod 数据中心 ID——而非 AWS 区域。
--endpoint-url
由同一数据中心 ID 生成。
每个命令都需要这两个标志：
--region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/
提示：在 https://console.runpod.io/user/storage/ 的存储页面，每个网络卷都会显示预填充的 
aws s3 ls
命令示例，其中已替换正确的 
--region
和 
--endpoint-url
。可使用该示例确认特定卷的准确参数。
各区域对应的数据中心 ID：
区域数据中心 ID
欧洲CZ-1, RO-1, IS-1, NO-1
美国CA-2, GA-2, IL-1, KS-2, MD-1, MO-1, MO-2, NC-1, NC-2, NE-1, WA-1

Key Commands

核心命令

Replace 
DATACENTER
with the datacenter ID of your network volume (e.g. 
CA-2
) and 
NETWORK_VOLUME_ID
with the volume ID (used as the S3 bucket name).
bash
undefined
将 
DATACENTER
替换为网络卷所在的数据中心 ID（例如 
CA-2
），将 
NETWORK_VOLUME_ID
替换为卷 ID（用作 S3 存储桶名称）。
bash
undefined

List files in a volume

列出卷中的文件

aws s3 ls
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/
aws s3 ls
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/

List a subdirectory

列出子目录

aws s3 ls
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/my-folder/
aws s3 ls
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/my-folder/

Upload a file

上传文件

aws s3 cp local-file.txt
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/
aws s3 cp local-file.txt
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/

Download a file

下载文件

aws s3 cp
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-file.txt ./
aws s3 cp
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-file.txt ./

Delete a file

删除文件

aws s3 rm
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-file.txt
aws s3 rm
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-file.txt

Sync a local directory to a volume

将本地目录同步到卷

aws s3 sync local-dir/
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-dir/

Path mapping: `/workspace/my-folder/file.txt` on a pod = `s3://NETWORK_VOLUME_ID/my-folder/file.txt` via S3.
aws s3 sync local-dir/
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
s3://NETWORK_VOLUME_ID/remote-dir/

路径映射：Pod 中的 `/workspace/my-folder/file.txt` = 通过 S3 访问的 `s3://NETWORK_VOLUME_ID/my-folder/file.txt`。

Troubleshooting

故障排查

bash
undefined
bash
undefined

Retry on timeout (large transfers)

超时后重试（大文件传输）

export AWS_RETRY_MODE=standard export AWS_MAX_ATTEMPTS=10
export AWS_RETRY_MODE=standard export AWS_MAX_ATTEMPTS=10

Extend read timeout for large files (seconds)

延长大文件读取超时时间（秒）

aws s3 cp large-file.zip
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
--cli-read-timeout 7200
s3://NETWORK_VOLUME_ID/
undefined
aws s3 cp large-file.zip
--region DATACENTER
--endpoint-url https://s3api-DATACENTER.runpod.io/
--cli-read-timeout 7200
s3://NETWORK_VOLUME_ID/
undefined