# 概述
<subtitle>安全存储凭证，并在沙箱出站 HTTPS 请求中由平台自动注入。</subtitle>

> **内测说明**：Secret 目前处于内测阶段，默认不开放。如需体验，请联系我们的技术支持开通。

Secret 用于托管 API Key、访问令牌等敏感凭证。凭证不会存放在沙箱内，而是保存在 UCloud 管控的安全存储中。沙箱只持有对 Secret 的引用，真实值由平台在沙箱外部按需注入。

## 为什么使用 Secret

如果把凭证写入环境变量、模板或沙箱内的文件，沙箱里运行的任何代码都能读取到它。使用 Secret 后，凭证与沙箱隔离，可以带来以下保护：

- **降低被攻击后的损失**：即使沙箱遭到攻击，攻击者也无法从沙箱内获取凭证，难以借此冒用您的身份或造成更严重的后果。
- **防止 AI Agent 泄露凭证**：沙箱内运行的 AI Agent 无法直接读取凭证，也就不会因为读到凭证而把它带进上下文，进而发送给模型服务商。
- **集中管理、按需轮换**：凭证只需保存一次，之后在网络规则中按名称引用。更新凭证后，运行中的沙箱无需重建即可使用新值。

## 工作原理

沙箱配置中只保存对 Secret 的引用，不包含真实值。沙箱发起匹配规则的出站 HTTPS 请求时，由沙箱外部的出站代理将真实值注入请求头。因此，沙箱内的代码始终接触不到凭证本身。

```mermaid
graph LR
  S[沙箱内代码] -->|请求，不含凭证| P[出站代理]
  P -->|注入 Secret 值| T[目标服务]
```

Secret 的值是**只写**的：只能在创建或更新时写入，任何查询、列表接口都不会返回它。

> 请在受信任的应用中管理 Secret，并且不要把 UCloud Sandbox 的 API Key 放进沙箱。Secret 归属于该 API Key 对应的项目。

> **注意**：只向您信任的目标服务注入凭证。接收方服务有可能在响应中把凭证原样返回给沙箱。

使用 UCloud Sandbox SDK，您可以：
- [创建 Secret。](/docs/agent-sandbox/secret/create.md)
- [在出站请求中注入 Secret。](/docs/agent-sandbox/secret/inject.md)
- [轮换 Secret，无需重启沙箱。](/docs/agent-sandbox/secret/rotate.md)
- [查看 Secret 列表与元数据。](/docs/agent-sandbox/secret/list.md)
- [删除 Secret。](/docs/agent-sandbox/secret/delete.md)

> 也可以使用 CLI 管理 Secret，参阅 [CLI 指南](/docs/agent-sandbox/product/cli.md)。

## 基本用法

```python
from ucloud_sandbox import Sandbox, Secret

# 保存星图平台的 API Key（只需一次）
Secret.create("modelverse_api_key", "your-modelverse-api-key")

# 创建沙箱时，在网络规则中引用 Secret
sandbox = Sandbox.create(
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()),
        "deny_out": lambda ctx: [ctx.all_traffic],
        "rules": {
            "api.modelverse.cn": [
                {
                    "transform": {
                        "headers": {
                            "Authorization": f"Bearer {Secret.fill('modelverse_api_key')}",
                        },
                    },
                },
            ],
        },
    },
)
```