@@ -28,12 +28,21 @@ These tools are not available in a conversation with several agents. Adding an a
 
 The agent never asks for credentials in chat. To create an agent, connect an integration or code host, or add a secret, MCP server, or skill, it opens the matching console dialog, prefilled where it can, for you to finish. Trying a [Decision](/build-your-team/decisions) on a sample message is not available here; use **Try with an example** in the Decision editor.
 
+## Attach files
+
+Use the composer's attach button to add files to a message. An image goes to the agent with the message itself. Any other file uploads to your deployment's object store first and appears as a chip above the composer; the message sends once every upload has finished. The agent receives the file's name and a short-lived download link, and fetches the file into its workspace when it needs it.
+
+- A message can carry up to 4 files, each within your deployment's upload limit; the composer tells you when a file is over it.
+- If your deployment has no object store configured, only images can be attached.
+- A message with files is never folded into a turn that is already running. It waits and runs as its own turn once the current one ends.
+
 ## Work with several agents
 
 Add agents before the first message from the Home composer, or add them to an existing Playground conversation.
 
 - A message without an `@AgentName` goes to every participant. Each agent may answer or stay silent.
 - An explicit `@AgentName` narrows that turn to the named participant or participants.
+- Files go only to the agents a message addresses. The other participants see that files were attached, by name, but cannot open them.
 - Every agent keeps its own configuration while the browser combines their activity into one conversation.
 
 ## When the session is saved
 
@@ -28,12 +28,21 @@ Playground 会在 Agent 的 Daemon 上创建一个真实的会话，使用与频
 
 Agent 绝不会在对话中索要凭证。创建 Agent、连接集成或代码托管、添加密钥、MCP 服务器或技能时，它会打开对应的控制台对话框，并尽量预先填好，由你来完成。在这里不能用示例消息试运行[决策](/build-your-team/decisions)；请在决策编辑器中使用**用示例试运行**。
 
+## 附加文件 [#attach-files]
+
+使用输入框的附件按钮为消息添加文件。图片会随消息本身一起发给 Agent。其他文件会先上传到你所部署环境的对象存储，并以标签的形式显示在输入框上方；所有上传完成后消息才会发出。Agent 收到的是文件名和一个短时有效的下载链接，需要时再把文件取到自己的工作区。
+
+- 一条消息最多附带 4 个文件，每个文件都不能超过部署环境的上传上限；超过时输入框会提示你。
+- 如果部署环境没有配置对象存储，则只能附加图片。
+- 带文件的消息不会并入正在运行的一轮，而是等待当前一轮结束后，作为单独的一轮运行。
+
 ## 与多个 Agent 协作 [#work-with-several-agents]
 
 可以在首页输入框发送第一条消息之前添加 Agent，也可以把它们加入已有的 Playground 对话。
 
 - 不带 `@AgentName` 的消息会发送给每个参与者。每个 Agent 可以回答，也可以保持沉默。
 - 明确的 `@AgentName` 会把该轮次限定到被点名的一个或多个参与者。
+- 文件只发给消息所指向的 Agent。其他参与者能看到附带了哪些文件（按文件名），但无法打开。
 - 每个 Agent 都保留自己的配置，而浏览器把它们的活动合并为一个对话。
 
 ## 会话何时被保存 [#when-the-session-is-saved]
 
@@ -187,6 +187,82 @@ docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
 
 The command is resumable and can also be rerun after rotating the Transit key. Vault workload identity is supported through `VAULT_JWT_ROLE`, `VAULT_JWT_PATH`, and `VAULT_AUTH_MOUNT` instead of `VAULT_TOKEN`.
 
+## File transfer and the object store
+
+Console file transfer needs an S3-compatible object store. With one, a person can attach any file to a [Playground](/build-your-team/agents/playground#attach-files) message, and the console can download workspace files of any size up to the store's limit. Bytes go straight between the browser or daemon and the store on short-lived signed URLs; the Control Plane only signs them and never sees file contents. Without a store, only images can be attached, and workspace downloads go through the Control Plane, up to 8 MiB per file.
+
+Signed URLs must be `https://`, and browsers and daemons reach the store directly, so the store needs an HTTPS origin they trust.
+
+### Bundled store (HTTPS overlay)
+
+The `compose.logto.https.yaml` overlay, which puts the stack and Logto sign-in behind Caddy HTTPS, also runs a [RustFS](https://rustfs.com) object store. Caddy serves it on its own HTTPS port, and a one-shot `object-store-setup` service creates the `agentconnect` bucket, its lifecycle rules, and a CORS rule for the console origin on every start. Add these to the overlay's `.env`:
+
+```dotenv
+AGENTCONNECT_OBJECT_STORE_HTTPS_PORT=1445
+AGENTCONNECT_OBJECT_STORE_ACCESS_KEY=agentconnect-store
+AGENTCONNECT_OBJECT_STORE_SECRET_KEY=<random-password>
+```
+
+The overlay refuses to start while any of the three is missing. Use all three Compose files in every command:
+
+```bash
+docker compose --env-file .env \
+  -f compose.yaml -f compose.logto.yaml -f compose.logto.https.yaml \
+  up -d
+```
+
+Check the store through Caddy:
+
+```bash
+curl -k https://<host>:1445/health
+```
+
+Browsers and daemons follow download links to that port, so they must trust the Caddy CA for it as well as for the console. The repository's [Caddy HTTPS guide](https://github.com/agentconnect-md/agentconnect/blob/main/docs/self-host-caddy-https.md) covers the whole overlay, including exporting and trusting the Caddy root certificate.
+
+### External bucket
+
+To use your own bucket instead, set `AC_FILE_TRANSFER` in `compose.env` to a one-line JSON document:
+
+```dotenv
+AC_FILE_TRANSFER='{"version":1,"endpoint":"https://s3.example.com","region":"us-east-1","bucket":"agentconnect","forcePathStyle":true,"credentials":{"source":"static","dir":"/run/secrets","accessKeyIdKey":"file_transfer_access_key_id","secretAccessKeyKey":"file_transfer_secret_access_key"}}'
+```
+
+| Field             | Meaning                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `endpoint`        | The store's `https://` origin; the AWS regional endpoint when omitted                                      |
+| `publicEndpoint`  | The origin browsers and daemons use, when it differs from the one the Control Plane reaches                |
+| `prefix`          | Optional key prefix inside the bucket                                                                      |
+| `forcePathStyle`  | `true` for MinIO, RustFS, and most self-hosted stores                                                      |
+| `credentials`     | Files holding the access key pair, read from `dir`                                                         |
+| `limits.maxBytes` | Largest file, default `512Mi`, at most `5Gi`                                                               |
+
+Mount the key files into the Control Plane with an override:
+
+```yaml
+# compose.file-transfer.yaml
+services:
+  control-plane:
+    secrets:
+      - file_transfer_access_key_id
+      - file_transfer_secret_access_key
+secrets:
+  file_transfer_access_key_id:
+    file: ./secrets/file-transfer-access-key-id
+  file_transfer_secret_access_key:
+    file: ./secrets/file-transfer-secret-access-key
+```
+
+```bash
+docker compose --env-file compose.env -f compose.yaml -f compose.file-transfer.yaml \
+  up -d --force-recreate control-plane
+```
+
+The bucket also needs:
+
+- **A lifecycle rule** that expires objects tagged `ac-cache=pending` under `<prefix>/src/` (or `src/` with no prefix) after 2 days. Until it exists, the Control Plane refuses transfers and logs the rule to add. The [chart README](https://github.com/agentconnect-md/agentconnect/blob/main/charts/agentconnect/README.md#bucket-lifecycle-rules) has the document and the commands for AWS and MinIO.
+- **A CORS rule** admitting the console origin for `GET` and `PUT`, with the `content-type`, `x-amz-checksum-sha256`, and `x-amz-tagging` headers.
+- **Permissions** for the key pair: `s3:PutObject`, `s3:PutObjectTagging`, and `s3:GetObject` under `<prefix>/src/*/transfer/`, and `s3:GetLifecycleConfiguration` on the bucket.
+
 ## Private certificate authorities
 
 A GitLab or Gitea instance presenting a certificate from a private authority needs that authority's bundle readable **at a file path that exists inside each process**, including the agent sandbox. Point every runtime at it:
@@ -209,6 +285,7 @@ The Relay never dials the instance — it only receives webhook deliveries — s
 - Replace every default secret and enable encrypted secret storage.
 - Set a connector encryption key if you use connectors, and back up its volume.
 - Put Web, Control Plane, Relay, and Logto behind HTTPS.
+- Give file transfer an HTTPS object store with its lifecycle rule, or leave it off.
 - Preserve WebSocket upgrades.
 - Back up PostgreSQL and test restores.
 - Keep Setup Server, PostgreSQL, and the connector gateway off the public network.
@@ -187,6 +187,82 @@ docker compose --env-file compose.env -f compose.yaml -f compose.vault.yaml \
 
 该命令可以断点续跑，也可以在轮换 Transit 密钥之后重新运行。Vault 工作负载身份可以通过 `VAULT_JWT_ROLE`、`VAULT_JWT_PATH` 和 `VAULT_AUTH_MOUNT` 来使用，以替代 `VAULT_TOKEN`。
 
+## 文件传输与对象存储 [#file-transfer-and-the-object-store]
+
+控制台的文件传输需要一个兼容 S3 的对象存储。有了它，用户可以在 [Playground](/build-your-team/agents/playground#attach-files) 消息中附加任意文件，控制台也能下载不超过存储上限的任意大小的工作区文件。文件字节通过短时有效的签名 URL 在浏览器或 Daemon 与存储之间直接传输；控制平面只负责签名，从不接触文件内容。没有对象存储时，只能附加图片，工作区文件经由控制平面下载，每个文件最大 8 MiB。
+
+签名 URL 必须是 `https://`，并且浏览器和 Daemon 会直接访问存储，因此存储需要一个它们信任的 HTTPS 源地址。
+
+### 内置存储（HTTPS 叠加配置） [#bundled-store-https-overlay]
+
+`compose.logto.https.yaml` 叠加配置把服务栈和 Logto 登录放在 Caddy HTTPS 之后，同时还会运行一个 [RustFS](https://rustfs.com) 对象存储。Caddy 在单独的 HTTPS 端口上提供它，一次性的 `object-store-setup` 服务会在每次启动时创建 `agentconnect` 存储桶、它的生命周期规则，以及允许控制台源地址的 CORS 规则。在叠加配置的 `.env` 中加入：
+
+```dotenv
+AGENTCONNECT_OBJECT_STORE_HTTPS_PORT=1445
+AGENTCONNECT_OBJECT_STORE_ACCESS_KEY=agentconnect-store
+AGENTCONNECT_OBJECT_STORE_SECRET_KEY=<random-password>
+```
+
+缺少其中任何一项时，叠加配置会拒绝启动。每条命令都要带上全部三个 Compose 文件：
+
+```bash
+docker compose --env-file .env \
+  -f compose.yaml -f compose.logto.yaml -f compose.logto.https.yaml \
+  up -d
+```
+
+通过 Caddy 检查存储：
+
+```bash
+curl -k https://<host>:1445/health
+```
+
+浏览器和 Daemon 会沿着下载链接访问这个端口，因此除了控制台之外，它们也必须为这个端口信任 Caddy CA。仓库中的 [Caddy HTTPS 指南](https://github.com/agentconnect-md/agentconnect/blob/main/docs/self-host-caddy-https.md)完整介绍了这个叠加配置，包括如何导出并信任 Caddy 根证书。
+
+### 外部存储桶 [#external-bucket]
+
+如果要改用你自己的存储桶，请在 `compose.env` 中把 `AC_FILE_TRANSFER` 设置为单行 JSON 文档：
+
+```dotenv
+AC_FILE_TRANSFER='{"version":1,"endpoint":"https://s3.example.com","region":"us-east-1","bucket":"agentconnect","forcePathStyle":true,"credentials":{"source":"static","dir":"/run/secrets","accessKeyIdKey":"file_transfer_access_key_id","secretAccessKeyKey":"file_transfer_secret_access_key"}}'
+```
+
+| 字段 | 含义 |
+| --- | --- |
+| `endpoint` | 存储的 `https://` 源地址；省略时使用 AWS 区域端点 |
+| `publicEndpoint` | 浏览器和 Daemon 使用的源地址，仅在与控制平面访问的地址不同时设置 |
+| `prefix` | 存储桶内可选的键前缀 |
+| `forcePathStyle` | MinIO、RustFS 和大多数自托管存储设为 `true` |
+| `credentials` | 存放访问密钥对的文件，从 `dir` 读取 |
+| `limits.maxBytes` | 单个文件上限，默认 `512Mi`，最大 `5Gi` |
+
+用一个覆盖文件把密钥文件挂载到控制平面：
+
+```yaml
+# compose.file-transfer.yaml
+services:
+  control-plane:
+    secrets:
+      - file_transfer_access_key_id
+      - file_transfer_secret_access_key
+secrets:
+  file_transfer_access_key_id:
+    file: ./secrets/file-transfer-access-key-id
+  file_transfer_secret_access_key:
+    file: ./secrets/file-transfer-secret-access-key
+```
+
+```bash
+docker compose --env-file compose.env -f compose.yaml -f compose.file-transfer.yaml \
+  up -d --force-recreate control-plane
+```
+
+存储桶还需要：
+
+- **一条生命周期规则**：让 `<prefix>/src/`（没有前缀时为 `src/`）下标记为 `ac-cache=pending` 的对象在 2 天后过期。在规则存在之前，控制平面会拒绝传输，并在日志中给出需要添加的规则。规则文档以及 AWS 和 MinIO 的命令见 [Chart README](https://github.com/agentconnect-md/agentconnect/blob/main/charts/agentconnect/README.md#bucket-lifecycle-rules)。
+- **一条 CORS 规则**：允许控制台源地址发起 `GET` 和 `PUT`，并允许 `content-type`、`x-amz-checksum-sha256` 和 `x-amz-tagging` 请求头。
+- **权限**：密钥对需要在 `<prefix>/src/*/transfer/` 下拥有 `s3:PutObject`、`s3:PutObjectTagging` 和 `s3:GetObject`，并在存储桶上拥有 `s3:GetLifecycleConfiguration`。
+
 ## 私有证书颁发机构 [#private-certificate-authorities]
 
 如果 GitLab 或 Gitea 实例出示的是由私有证书颁发机构签发的证书，就需要让该机构的证书包**在每个进程内部都存在的文件路径**上可读，包括 Agent 沙箱。让每个 Runtime 都指向它：
@@ -209,6 +285,7 @@ Relay 从不主动连接该实例——它只接收 Webhook 投递——因此
 - 替换所有默认密钥，并启用加密的密钥存储。
 - 如果使用连接器，设置连接器加密密钥，并备份其卷。
 - 把 Web、控制平面、Relay 和 Logto 放在 HTTPS 之后。
+- 为文件传输配置带生命周期规则的 HTTPS 对象存储，或者不启用它。
 - 保留 WebSocket 升级。
 - 备份 PostgreSQL 并测试恢复。
 - 让 Setup Server、PostgreSQL 和连接器网关远离公共网络。
@@ -130,6 +130,7 @@ docker compose down --volumes
 | Setup Server | Docker, loopback only | Configure deployment auth and providers |
 | PostgreSQL | Docker | Persist deployment and Control Plane data |
 | Logto OSS | Optional overlay | Local sign-in |
+| Object store (RustFS) | HTTPS overlay | File uploads and large workspace downloads; see [File transfer](/self-hosting/docker-compose/configuration#file-transfer-and-the-object-store) |
 | Daemon | Host or another machine | Run agents and hold local data |
 
 The Relay is included so GitHub, webhooks, webchat, and HTTP bot callbacks work without changing the stack. Direct Slack Socket Mode, Telegram, Discord, and Lark / Feishu connections continue to run between the daemon and their providers.
 
@@ -130,6 +130,7 @@ docker compose down --volumes
 | Setup Server | Docker，仅回环地址 | 配置部署的认证与提供方 |
 | PostgreSQL | Docker | 持久化部署和控制平面数据 |
 | Logto OSS | 可选叠加配置 | 本地登录 |
+| 对象存储（RustFS） | HTTPS 叠加配置 | 文件上传和大文件工作区下载；见[文件传输](/self-hosting/docker-compose/configuration#file-transfer-and-the-object-store) |
 | Daemon | 宿主机或另一台机器 | 运行 Agent 并保存本地数据 |
 
 包含 Relay 是为了让 GitHub、Webhook、网页聊天和 HTTP 机器人回调无需改动服务栈即可工作。Slack Socket Mode、Telegram、Discord 和 Lark / 飞书的直连仍然在 Daemon 与各自的提供方之间运行。