Localsandbox 是一个轻量级开源库，为 AI 代理提供隔离的虚拟文件系统、安全的 Bash 执行环境和沙箱化的 Python 代码运行能力，基于 AgentFS、just-bash 和 Pyodide 构建，让代理在本地也能拥有类似虚拟机的自主操作权限，同时避免破坏真实系统。
智能体从只会聊天，进化到会调用工具，再到直接读写文件运行代码，算力与风险同步放大。Localsandbox 用虚拟文件系统 Bash 子集 与 WASM Python，给智能体一座轻量可控的“实验室”，把能力与边界一起交付。
智能体能力每提升一个层级，对执行环境的需求就升级一次：最早阶段，模型只负责生成文本，世界被压缩进提示词；随后，工具调用出现，文本开始驱动真实世界动作；再往前一步，文件系统与代码执行进入舞台，智能体拥有了“长期记忆”和“动手能力”。
能力扩张自然带来风险扩张，于是沙盒成为承接这一切的关键结构。Localsandbox 组合 AgentFS、just-bash 与 Pyodide，用轻量方式复刻出一台“准虚拟机”，让智能体在安全边界内全速运转。
从文本生成时代起跑
早期的大语言模型就像一个只会听指令背书的学生，给一段文字，就吐出一段回应。
最早的智能模型工作方式极为纯粹，输入一段文字，输出一段文字，像一台高级自动补全引擎。
为了让输出更贴近目标，需要在提示词中塞入背景资料、规则说明、上下文摘要，于是提示工程与检索增强生成逐渐成形。
为了让它回答得更准，人们发明了“检索增强生成”（RAG）技术，相当于临时塞一本参考书进它的脑子里。相关信息被提前装箱，模型在限定空间里推理组合。
但问题来了——模型不能主动问“我需要查哪本书？”也不能说“这题太难，让我先算个草稿”。所有信息都得提前打包好，像给婴儿喂糊糊一样一口一口喂进去。
这种方式在问答与内容生成领域表现稳定，却很快暴露边界：所有素材需要预先准备，任何遗漏都会让模型陷入信息真空。
文本一次性投喂的结构，让系统更像考试答题，而非持续做事的实体。这种模式虽然简单，却严重限制了模型处理复杂任务的能力。想象一下，如果让一个学生做数学大题，却不允许他拿草稿纸、不准查公式表，连计算器都不能碰，那效率得多低？
于是，聪明人开始琢磨：既然模型能理解工具的概念，为什么不直接教它“调用工具”？
工具调用：让 AI 学会“伸手要东西”
当文本生成遇到边界，一个自然问题浮现：模型是否可以主动索取所需信息，甚至触发真实动作。工具调用因此登场。
系统为模型提供一组可调用方法，模型通过特定文本格式表达调用意图，执行层解析文本，完成 API 请求、数据库查询、计算任务，再把结果反馈给模型。
工具调用的出现，相当于给 AI 配了一套“技能卡牌”。模型不再只是被动输出文本，而是可以主动声明：“我要调用天气查询工具，参数是北京，时间是今天。”系统接收到这个结构化请求（通常是 JSON 格式），就去执行对应操作，再把结果塞回给模型继续推理。
这种机制让 AI 能动态获取信息、操作外部系统，甚至请求人类帮忙。
文本成为控制协议，JSON 变成信号灯。
由此，智能体雏形诞生。
模型开始参与流程决策，工具承担执行职责。
大家发现很多工具其实是重复造轮子——比如每个开发者都要写一遍“查 Slack 消息”或“读 Google 日历”的接口。标准化接口逐步出现，MCP （Model Context Protocol）正是在这种背景下形成，通过统一规范暴露 API，减少重复造轮子的工程消耗。它像一套通用插座标准，让各种 API 自动变成 AI 能识别的工具插头。
不过，这也带来新问题：万一 AI 误用了某个高危工具，比如删数据库或发邮件，后果不堪设想。好在早期工具都是人工编写的，开发者能控制权限边界，就像给小孩玩剪刀前先磨钝刀尖。
文件系统与代码执行：AI 开始“自己写作业”
当软件开发场景被纳入视野，工具调用进一步进化。复制粘贴代码的节奏明显拖慢协作效率，于是读写文件成为核心能力。
真正引爆生产力的转折点，是让 AI 能直接读写文件并运行代码。
以前用 Copilot 或 Claude 写代码，得手动复制粘贴来回切换窗口，效率堪比用算盘解微积分。后来，AI 实验室意识到：如果模型能像真人程序员一样，在自己的“小房间”里新建文件、编辑代码、运行测试、看报错日志，那开发效率将指数级提升。
于是，Cursor、Copilot Workspace、Claude Code 等产品纷纷赋予 AI 一个虚拟工作区。
智能体可以直接查看项目目录，修改源文件，运行测试命令。
更进一步，与其为每个功能写专用工具（比如“搜索文件”“运行测试”），不如直接开放 Bash 命令行——让 AI 自己敲 grep、ls、pytest，甚至写个脚本自动化流程。
grep、lint、test 这些开发者日常工具，被统一抽象为可执行指令。
Bash 执行能力让智能体具备即时造工具的能力，脚本生成与运行形成闭环。长时间任务得以展开，数小时持续改进成为现实。
这时候，AI 不再是工具使用者，而是工具创造者。它能根据任务即时发明新工具，比如写个 Python 脚本解析 CSV，再用另一个脚本生成图表。
但危险也随之而来：一句 rm -rf / 就能让整个系统灰飞烟灭。
因此，大多数系统默认开启“确认模式”，每次执行命令都弹窗问“你确定吗？”，除非用户胆大包天开启 YOLO（You Only Live Once）模式——那可真是“生死由命，富贵在天”了。
当文件系统与代码执行成熟，应用范围迅速超出软件开发：
数据分析场景只需要把数据文件放入目录，再赋予 Python 执行能力。
表格处理场景通过读取 Excel 文件并运行分析脚本完成。
对账流程通过加载多份数据，匹配规则，输出结果文件。
上下文窗口限制在此刻被绕开，数据规模由磁盘容量决定。
智能体工具集开始趋向极简，只保留读写文件与运行代码，复杂性转移到智能体生成的程序中。
沙盒问题浮出水面
当 AI 代理能在本地机器上自由读写文件、运行任意代码，安全隐患就浮出水面。
对个人用户来说，可能只是误删文档；但对企业级产品而言，成千上万个代理同时运行在服务器上，若缺乏隔离，一个代理可能偷看另一个的数据，甚至瘫痪整台机器。这其实不是新问题——早在互联网时代，浏览器就用 V8 引擎和 WebAssembly 隔离网页脚本；云计算用 Docker 容器隔离应用；云服务商则用 gVisor、Firecracker 等轻量虚拟机保护租户。
如今，这些成熟技术被移植到 AI 领域：Modal、Azure Container Apps、Google Cloud Run、AWS AgentCore 等平台都提供“动态会话”服务，为每个代理分配独立沙箱。但这些方案往往重、贵、依赖云端，不适合本地开发或快速原型验证。
Localsandbox 的定位与组合
Localsandbox 正是为了填补这一空白而生。
它不搞重型虚拟机，而是用三个精巧组件拼出一个“伪虚拟机”：
第一层是 AgentFS，由 Turso Database 团队开发，用 SQLite 作为后端存储，构建出一个完全虚拟的文件系统。这意味着所有文件操作都发生在内存或单个 .db 文件中，不会污染真实磁盘，还能随时备份、恢复、迁移。
第二层是 just-bash，由 Vercel 团队打造，它不是调用系统真实的 Bash，而是在 TypeScript 里实现了一个 Bash 子集解释器，专门对接虚拟文件系统。所以当 AI 输入 ls 或 cat README.md，实际是在 AgentFS 的虚拟空间里操作，根本碰不到主机文件。
第三层是 Pyodide，一个在 WebAssembly 中运行的完整 Python 发行版，通过 Deno 运行时加载，并将 AgentFS 挂载为其文件系统根目录。
这样，AI 写的 Python 代码（比如 import pandas as pd; df = pd.read_csv('data.csv')）就能安全读写虚拟文件，所有计算都在 WASM 沙箱内完成，无法访问网络或系统资源。
这三层组合起来，就形成了一个高度便携、启动迅速、资源占用低的本地代理执行环境。
为什么这不只是“又一个沙箱”？
Localsandbox 的独特之处在于“轻”与“组合”。它不重复造轮子，而是巧妙集成现有优秀项目：AgentFS 解决了状态持久化与隔离，just-bash 提供了熟悉的命令行体验，Pyodide 则带来完整的 Python 生态。
三者通过标准接口拼接，形成闭环。
更重要的是，它专为 AI 代理设计——所有输入输出都可通过函数调用接入主流代理框架（如 LangChain、LlamaIndex），让开发者只需几行代码就能给代理“装上手脚”。
例如，一个数据分析师代理拿到销售数据 CSV 后，可自动写 Python 脚本清洗、聚合、绘图，再把结果存为新文件；一个财务对账代理能读取两份账单，运行比对逻辑，输出差异报告。
这些任务不再受限于上下文窗口长度，因为数据全在虚拟文件系统里，AI 可以分步处理、反复迭代。
三者组合后，智能体获得一种“准虚拟机”体验：文件系统具备持久性与可移植性，Bash 提供流程控制与工具组合能力，Python 承担计算与分析任务。执行环境运行在 WASM 沙盒内，与宿主系统保持清晰边界。整体架构强调轻量与可组合性，适合嵌入现有智能体框架，通过工具封装即可使用。开发者可以在本地快速验证智能体流程，再根据需求迁移到更强隔离方案。
超越编程：沙箱代理的万能应用场景
虽然起源于代码生成，但沙箱代理的潜力远不止软件开发。任何需要“读取数据→处理逻辑→输出结果”的任务都适用。比如，一个法律合同分析代理，可将 PDF 合同转为文本存入虚拟文件系统，再写 Python 脚本提取关键条款、比对模板、标出风险点；一个科研文献综述代理，能下载多篇论文 PDF，用脚本批量解析、向量化、聚类，最后生成综述草稿；甚至一个诗歌创作代理，也可在沙箱中维护一个“灵感库”文件，不断追加意象、韵脚、结构模板，通过代码重组生成新诗。关键在于，代理拥有了“工作记忆”和“动手能力”——它不再是一次性吐出答案的 oracle，而是一个能持续操作、试错、优化的数字工作者。这种范式转移，正是从“问答型 AI”迈向“行动型 AI”的关键一步。
技术细节：如何让虚拟文件系统“活”起来
AgentFS 的核心创新在于用 SQLite 模拟 POSIX 文件系统。每个文件、目录、符号链接都被映射为数据库表中的记录，元数据（如修改时间、权限）也一并存储。读写操作通过 SQL 事务保证原子性，避免并发冲突。
更妙的是，整个文件系统可导出为单个 .sqlite 文件，方便版本控制或跨设备同步。
just-bash 则实现了 cd、ls、cat、grep、echo、mkdir、rm 等常用命令的语义，但所有路径解析都指向 AgentFS 的虚拟根目录。例如，当 AI 执行 grep "error" logs/app.log，just-bash 会调用 AgentFS 的 readFile 接口读取虚拟文件内容，再在内存中执行正则匹配。
Pyodide 的集成则通过 Deno 的 WASI（WebAssembly System Interface）支持，将 AgentFS 挂载为 /sandbox 目录。Python 代码中的 open('/sandbox/data.csv') 实际调用的是 AgentFS 的底层读取函数。整个执行环境无网络、无系统调用、无全局状态，确保绝对安全。
项目特点
特征
- 沙盒执行：在隔离环境中运行bash命令
- Python执行：通过Pyodide（WebAssembly）在同一个虚拟文件系统上运行Python
- 持久化文件操作：所有文件操作在SQLite中的命令之间持久化
- 键值存储：用于代理状态管理的独立KV API
- 命令历史记录：跟踪所有执行的命令的时间戳和结果
- 快照恢复：导出/恢复完成沙盒状态
- 执行限制：可配置的DOS保护（循环迭代，命令计数）
- 异步支持：通过asyncio.to_thread提供完整的异步API
- 上下文管理器：使用with语句清理资源管理
LocalSandbox使用TypeScript shim（在Deno上运行）将Python连接到：
- just-bash：用TypeScript编写的bash解释器/模拟器
- AgentFS：基于SQL的虚拟文件系统
- Pyodide：编译为WebAssembly的Python解释器，用于沙箱Python执行
- 打开SQLite数据库
- 通过just-bash或Pyodide执行操作
- 将更改保留回SQLite
- 返回JSON结果
安装
pip install localsandbox
或者
uv add localsandbox
点击标题进入项目！