ValetFS 解决的是本地 AI 智能体使用 API 密钥时的安全问题。传统做法通常将密钥写入 shell 配置文件、环境变量或 dotfile，容易被后续的提示注入攻击读取。ValetFS 将密钥保留在手机端（受 Face ID 保护），当电脑上的工具或 AI 智能体需要密钥时，由 valetfs 守护进程临时借入内存，使用完毕即归还。关闭应用后启动宽限计时器，超时后守护进程卸载并擦除自身，磁盘上不留任何明文。
主要能力
- 零后端、点对点、内存虚拟文件系统：仅在成对移动应用允许时，向 AI 智能体暴露短时令牌和密钥。
- 提供 Go 守护进程和 Cloudflare Worker 信令存根。
- 支持 FUSE 挂载，若不可用则自动回退到本地 WebDAV 端点。
- 提供本地 CLI 命令：ls、status、cat、exec、cp、mv、rm、mkdir、rmdir 等。
- 密钥只存在于守护进程堆内存中；Ctrl-C、远程锁定/卸载或应用忘记会话时，守护进程卸载并零擦除内存；未被认领时会在宽限期后自动锁定。
- 连接密钥本身包含信令 URL，无需额外指定 --signaling。
- 默认使用 WebSocket 传输（Cloudflare Durable Object）并端到端加密，也支持 --transport webrtc 的旧版 P2P 路径。
- 支持通过 CLI 进行两台设备之间的 Vault 配对，无需移动应用。
使用方式
AI 智能体可通过本地 CLI 访问内存文件系统。安全用法是使用 valetfs exec，将密钥作为环境变量注入子进程，而不是用 cat 将密钥打印到 stdout（否则会进入智能体记录、shell 历史和日志）。exec 会原样传递子进程的 stdout、stderr 和退出码，可嵌入现有管道或 && 链。--as-file 可将密钥物化为内存支撑目录中的 0600 权限文件，退出时清零并删除。多个选项可重复使用，一次注入多个密钥。ls 和 status 仅报告名称、大小和守护进程状态，不显示内容，可安全调用。
若使用 Claude Code 等会拦截 valetfs cat 的智能体，需由人工执行一条命令将 valetfs 相关权限合并到用户级设置文件（$CLAUDE_CONFIG_DIR/settings.json 或 ~/.claude/settings.json），保留其他键及其顺序，备份原文件为 settings.json.valetfs-backup，重复执行无副作用。写入和删除（cp、mv、rm）默认不授予，cat 也需通过 --allow-cat 显式添加。
AI 智能体快速连接会话的步骤：
- 安装 valetfs CLI（Linux x86_64 / arm64），无需 root、驱动或 FUSE；若 FUSE 不可用，守护进程通过回环 WebDAV 端点服务文件。无 sudo 安装：... | INSTALL_DIR=$HOME/.local/bin bash，并确保该目录在 PATH 中。macOS/Windows 或不支持的架构可从源码构建：git clone https://github.com/winm2m/valet-fs && cd valet-fs && go build -o valetfs ./cmd/valetfs。 1b. 安装智能体技能（Claude Code 及其他支持技能的智能体），将 valetfs 技能放入 ~/.claude/skills/。设置 SKILL_DIR= 可安装到单个项目。
- 使用用户提供的连接密钥加入会话，该命令以守护进程身份连接、发布 E2EE 公钥并启动内存文件系统。保持运行后，用户从应用推送密钥，即可用本地 CLI 读取。
Vault 路径需要 fs: 前缀，裸 /keys 会被视为本机路径。ls/cat/exec 会拒绝裸路径，而 cp/mv 接受两种路径并推断方向，省略前缀会静默将明文写入磁盘。
适用场景
- 本地 AI 智能体或编码助手需要临时使用 API 密钥，但希望避免密钥落盘。
- 希望将密钥集中保留在手机端，通过生物识别授权后临时出借。
- 需要在没有云工作负载身份联合的本地环境（笔记本、家庭服务器、容器）中安全管理密钥。
限制与安全保证
- 守护进程在每次启动时先执行卸载（fusermount -uz 或 Windows net use /delete）再重新挂载，确保挂载幂等。
- 收到 SIGINT/SIGTERM 时优雅关闭：卸载后清除内存中所有文件内容。
- 磁盘上无明文：$VALETFS_GIT_DIR 下的 diff 仓库只包含 sha256、大小和路径清单行，不含令牌内容。
- 配额执行：MemFS 拒绝超过配置集群配额（--quota-mb，默认 5MB）的写入。
- exec 不会将密钥值写入自身输出，密钥通过环境变量传给子进程；失败时只报告 vault 路径，格式错误的 env 文件仅报告行号，绝不输出文件内容。--as-file 在内存支撑目录中以 0600 权限物化，并在所有退出路径（包括信号终止）清零并删除。
- 内部 vfs 和 sync 包有无头单元测试，覆盖内存擦除、配额执行、路径穿越拒绝和清单不泄露。
项目当前实现优化为每个会话首次控制器配对；若重新加入超时，需创建新的 serve 会话。TURN 凭证不嵌入源码或二进制，由 Cloudflare Worker 使用机密签发短时凭证。