FUSE 文件系统接口

把 Agent 的运行过程，放到可检查的路径上。

CortexFS 在 /ctx 挂载模型、agent、tool 和持久 session——一个可用 ls、cat、执行、安全控制和审计的小型 Unix ABI。

开始安装查找使用指南 GitHub

018 个稳定根名称02通过 FUSE 挂载03受策略约束04持久 JSONL

稳定的根 ABI$ ls /ctx

statusbinmodelagenttoolchannelhomeshared

modelmodel 是纯推理文件：读取元数据，执行一次推理。

快速开始

安装、检查，再开始工作。

需要 Linux、systemd 与 FUSE。安装后先检查挂载，再配置供应商并打开会话。

阅读完整安装文档 →

01
安装
安装器检查系统依赖，并在修改前提示确认。也可选择原生 Linux 安装包。
```
curl -fsSL https://raw.githubusercontent.com/LIghtJUNction/cortexfs/main/scripts/install.sh | sh
```
02
检查运行状态
启动挂载，确认目录与运行时状态。供应商凭据需另外配置。
```
sudo systemctl enable --now cortexfs.service
ctx doctor
```
03
打开工作会话
配置好供应商后，在项目目录运行 ctx。下次用 ctx resume 继续当前目录的会话。
```
ctx
# 下次继续
ctx resume
```

项目介绍

快速了解 CortexFS。

从 /ctx 的稳定 ABI，到 model、agent、tool 与持久 session 的整体设计。

真实运行，而非概念图

看 runtime 真正在工作。

早期版本的运行录像使用 coder；当前默认 agent 为 executor，日常入口为 ctx。

三类可执行对象，一份持久历史

Runtime 的关键部分都能被直接操作。

CortexFS 只提供三类可执行对象，并用普通文件保存 session 历史，让 shell、权限和普通文件承担它们已经擅长的工作。

01model

模型是纯推理文件

读取文件得到元数据，执行文件完成一次推理。供应商连接与 API 格式差异留在统一模型 ABI 之后。

/ctx/model/main → provider route

02agent

Agent 是受策略约束的编排者

Agent 以可执行对象和 socket 暴露；Linux 身份、mount、cwd、model 与 policy 共同限定它能看见和执行什么。

/ctx/agent/executor  +  executor.sock

03tool

Tool 是可执行能力端点

Agent 通过 tsh 调用 tool。tsh 只沿 CTX_PATH 查找能力，不会回退到 host PATH。

CTX_PATH=/ctx/tool:/ctx/home/<uid>/tool

04session

Session 保存原始历史

messages.jsonl 与 events.jsonl 持久追加；prompt context 是可丢弃、可重建的工作集。

session/default/{messages,events}.jsonl

可审计的权限边界

Linux 权限与 runtime policy 在路径上相交。

mount ∩ uid/gid/mode ∩ policy ∩ CTX_PATH ∩ noexec

可见性不是 prompt 里的承诺。mount、uid/gid/mode bits、CortexFS policy、CTX_PATH 与 noexec 共同形成 agent 的实际权限。

供应商中立

变化的 API 之上，保持一个稳定 ABI。

one ABI / changing APIs

CortexFS 负责路径、对象生命周期、权限与 session 语义；协议适配层负责供应商连接和 API 事件适配。供应商细节不会膨胀成新的根目录。

看见mount ∩ uid/gid/mode

发现CTX_PATH

执行policy ∩ noexec

最终权限 = 所有边界的交集root 只包含稳定对象类别

让 runtime 回到 Unix

小到足以审计，实用到足以构建。

从规范理解稳定边界，在 GitHub 查看实现，或直接挂载 /ctx 开始使用。

阅读规范 GitHub 开始安装