沙箱为智能体生成的命令提供受限的执行环境，确保智能体在安全隔离的环境中运行命令，防止未经授权的文件访问。

支持的操作系统

• macOS
• Linux：Debian 10 及以上、Ubuntu 20.04 及以上（TRAE 暂不支持 Linux 客户端，需通过 Remote SSH 和 AppArmor 实现）

安全策略：文件访问控制

💡提示
- 当前安全策略不涉及网络访问。
- 读写权限继承当前用户权限；当读写与只读权限冲突时，以只读权限为准。

启用沙箱后，TRAE 的文件目录访问权限如下：

权限类型	目录类型	目录列表
只读	项目目录中的受保护目录	.vscode
根目录	/（默认策略：所有未显式声明为可写的目录均为只读）
读写	项目目录	除 .trae、.vscode 和 .git 之外的项目文件与目录
临时目录	· macOS：/tmp、/var/folders、TMPDIR 环境变量路径    · Linux：/tmp、·TMPDIR· 环境变量路径
缓存目录	· macOS：~/Library/Caches、~/.cache、XDG_CACHE_HOME 环境变量路径    · Linux：~/.cache、XDG_CACHE_HOME 环境变量路径
通用工具依赖目录	~/.local/lib、~/.local/bin、~/.local/share（通常用于 pip、uv/uvx、npm/pnpm、cmake 等工具的依赖目录）
常用语言的工具链及其依赖目录	Go、Java、Python、Node.js、Rust 和 C++ 等常用语言的工具链及其依赖目录。

使用流程

第一步：在操作系统中配置环境

使用沙箱前，需要根据你所使用的操作系统，完成相应的环境配置。

macOS

基于 macOS 的 sandbox-exec 工具，TRAE 会自动为你创建一个受限的命令执行环境。你无需进行任何额外配置。

Linux

TRAE 无法在本地 Linux 环境中直接启用沙箱，仅支持通过 Remote SSH 连接到远程 Linux 主机，并基于 AppArmor 模块实现沙箱。因此，你需要在远程 Linux 环境中加载 AppArmor 模块并安装 AppArmor 用户态工具集。环境步骤如下：

1. 在 TRAE 中，使用 Remote SSH 功能连接你的 Linux 远程主机。详细步骤参考使用 SSH 开发（Remote SSH）。

2. 在通过 Remote SSH 连接的远程 Linux 环境中，检查 AppArmor 模块当前是否已被添加至 LSM 模块链并启用。

   ## 检查 LSM 模块链中是否已包含 AppArmor 模块
   cat /sys/kernel/security/lsm | grep apparmor && echo ok  
   ## 检查 AppArmor 模块是否已启用
   [[ "$(cat /sys/module/apparmor/parameters/enabled)" == "Y" ]] && echo ok

3. 如果 AppArmor 模块当前未被添加和启用，在 Linux 标准发行版中添加并启用 AppArmor 模块。步骤如下：

   💡注意
   - 由于存在难以枚举的各类定制内核，且在不同环境中，各个发行版的内核在启用 AppArmor 模块的方式上存在差异，因此无法保证 AppArmor 模块一定能够正常工作，甚至可能导致系统无法启动。建议仅在具备相关条件且对内核开发、运维与调试有经验的情况下再尝试。
   - 为排除个体差异性，此处仅提供主要步骤。若想了解各步骤的具体细节，需结合实际情况查阅相关资料。

   a. 运行以下命令，确认内核中是否已包含 AppArmor 模块。若未包含，则无法操作后续步骤。

   cat /boot/config-* | grep -i apparmor

   如果输出类似以下信息（不同发行版或内核版本可能略有不同），则表示内核中已包含 AppArmor 模块:

   CONFIG_SECURITY_APPARMOR=y
   CONFIG_DEFAULT_SECURITY_APPARMOR=y
   CONFIG_LSM="landlock,lockdown,yama,integrity,apparmor"

   某些发行版在内核编译阶段就默认启用了 AppArmor，即使没有在启动参数中显式写入 apparmor=1。可通过以下命令进一步确认默认安全模块配置中是否包含 AppArmor：

   cat /boot/config-$(uname -r) | grep "CONFIG_DEFAULT_SECURITY"
   cat /boot/config-$(uname -r) | grep "CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE"

b. 为内核添加 AppArmor 模块的启动参数：
i. 检查以下 GRUB 配置文件：/etc/default/grub、/boot/grub/grub.cfg、/boot/efi/EFI/{distro_name}/grub.cfg 和 /etc/grub.d/。 ii. 在上述配置文件中找到 GRUB_CMDLINE_LINUX_DEFAULT，然后向其中添加 AppArmor 模块的启动参数：apparmor=1 security=apparmor。 c. 根据你所使用的发行版，执行相关命令来更新 GRUB。 d. 重启操作系统，让新的内核启动参数生效。 e. 验证 AppArmor 模块是否已启用： i. 运行以下命令，检查 LSM 模块链中是否包含 AppArmor 模块。

cat /sys/kernel/security/lsm | grep apparmor && echo ok

ii. 运行以下命令，检查 AppArmor 模块是否已启用。

[[ "$(cat /sys/module/apparmor/parameters/enabled)" == "Y" ]] && echo ok

iii. 运行以下命令，查看内核的启动日志，检查内核的 command-line 参数中是否已包含 AppArmor。

```Bash
cat /proc/cmdline | grep -i apparmor
```

第二步：在 TRAE 中启用沙箱

在 TRAE 中启用沙箱后，智能体将自动在沙箱中运行命令。启用沙箱的步骤如下：

1. 在 IDE 模式界面中，点击界面右上角的 设置 图标，进入设置中心。

   或

   在 SOLO 模式界面中，点击对话面板右上角的 设置 图标，进入设置中心。

2. 在左侧导航栏中，选择 ，进入 面板。
3. 在 部分的 处，为 IDE 和/或 SOLO 模式选择 模式。

4. 在 IDE / SOLO 处，按需将命令前缀加入白名单。

   白名单中的命令将跳过沙箱，直接在沙箱外执行。
   

第三步：为项目生成专属的沙箱配置（仅 Linux）

通过远程 Linux 环境实现的沙箱是受限的，因此需要为项目生成专属的沙箱配置，确保沙箱能正常工作。

💡提示
在远程 Linux 环境中使用沙箱时，每次打开一个新项目，都需要为该项目生成专属的沙箱配置。

1. 在 区域顶部的提示条中，点击最右侧的 按钮，复制 sudo 命令。
2. 在 TRAE 中，打开终端，然后运行该 sudo 命令。
3. 命令运行完成后，点击提示条中的刷新按钮，完成沙箱配置。

若你未按照上述步骤预先配置项目级沙箱，当智能体遇到需运行的命令时，会在对话流中提示你配置沙箱。

高风险命令的运行策略

在智能体运行过程中，若出现无法在沙箱中运行的高风险命令，系统会在对话流中提示。你可以按需选择：

• 跳过：跳过该命令，不运行。
• 添加{runningCommandList} 到白名单：将该命令的前缀添加到白名单，之后可在沙箱外运行相关命令。
• 运行：本次在沙箱中运行该命令。