agent-fs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-fs CLI

agent-fs is an agent-first filesystem with full versioning, full-text search (FTS5), and semantic search. It provides a CLI that outputs JSON, making it ideal for agent workflows. Files are organized in drives within orgs.

agent-fs 是一款面向Agent的文件系统，具备完整版本控制、全文搜索（FTS5）和语义搜索功能。它提供的CLI输出JSON格式内容，非常适合Agent工作流。文件在组织（org）内的驱动器（drive）中进行管理。

Storage Backends

存储后端

agent-fs stores file bytes in a pluggable storage backend. The durable value — version history, comments, and search — lives in SQLite and works identically on every backend.

Backend	Setup	Versioning tier	`signed-url`
S3 / MinIO (default)	`agent-fs onboard -y` (local MinIO, needs Docker) or `--s3-*` flags for AWS/R2/etc.	Full — `revert` + historical `diff` via S3 object versioning	Real presigned URL (public, time-limited)
Local filesystem	`agent-fs onboard --filesystem` (no Docker, no S3)	Full — `revert` + historical `diff` via content-addressed blobs on disk	Falls back to an authenticated in-app link (requires sign-in; does not expire)

Both backends are full-tier: every op — including

revert

and historical

diff

— works. Future backends may be basic-tier (no object versioning): on those,

revert

and historical

diff

are unavailable and fail cleanly with an

UNSUPPORTED_OPERATION

error (HTTP 422) rather than a raw storage error — current content, listing, comments, and search keep working. Check a backend's capabilities before relying on versioning if you're unsure which backend a drive uses.

agent-fs 采用可插拔存储后端存储文件字节。版本历史、评论和搜索等持久化数据存储在SQLite中，且在所有后端中的工作方式完全一致。

后端	配置方式	版本控制层级	`signed-url` 特性
S3 / MinIO（默认）	`agent-fs onboard -y` （本地MinIO，需要Docker）或使用 `--s3-*` 参数配置AWS/R2等	完整层级 — 支持通过S3对象版本实现 `revert` 和历史 `diff`	生成真实的预签名URL（公开、限时）
本地文件系统	`agent-fs onboard --filesystem` （无需Docker、无需S3）	完整层级 — 通过磁盘上的内容寻址Blob实现 `revert` 和历史 `diff`	回退到带认证的应用内链接（需登录，永不过期）

两种后端均为完整层级：所有操作（包括

revert

和历史

diff

）均可正常运行。未来的后端可能为基础层级（无对象版本控制）：在此类后端上，

revert

和历史

diff

不可用，会返回

UNSUPPORTED_OPERATION

错误（HTTP 422）而非原始存储错误，但当前内容、文件列表、评论和搜索功能仍可正常使用。若不确定驱动器使用的后端类型，请在依赖版本控制功能前检查后端的能力。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Set up (local MinIO — requires Docker)

1. 配置（本地MinIO — 需要Docker）

agent-fs onboard -y

...or with no Docker/S3 at all — store bytes on the local filesystem:

...或完全不使用Docker/S3 — 将字节存储在本地文件系统：

agent-fs onboard --filesystem # uses ~/.agent-fs/storage agent-fs onboard --filesystem --storage-root /data/agent-fs # custom dir

agent-fs onboard --filesystem # 使用 ~/.agent-fs/storage agent-fs onboard --filesystem --storage-root /data/agent-fs # 自定义目录

2. Optionally start the daemon (CLI auto-detects and works without it)

2. 可选：启动守护进程（CLI会自动检测，无需手动操作也可运行）

agent-fs daemon start

3. Start using it

3. 开始使用

echo "hello world" | agent-fs write docs/readme.txt -m "initial version" agent-fs cat docs/readme.txt


For custom S3 (AWS, R2, etc.), use flags: `agent-fs onboard --s3-endpoint <url> --s3-bucket <name> --s3-access-key <key> --s3-secret-key <key>`.

The local-filesystem backend (`--filesystem`, equivalently `--storage local`) needs no Docker and no S3 — bytes are stored under `--storage-root` (default `~/.agent-fs/storage`), with every version content-addressed so `revert` and historical `diff` work the same as on S3.

echo "hello world" | agent-fs write docs/readme.txt -m "initial version" agent-fs cat docs/readme.txt


对于自定义S3（AWS、R2等），使用参数：`agent-fs onboard --s3-endpoint <url> --s3-bucket <name> --s3-access-key <key> --s3-secret-key <key>`。

本地文件系统后端（`--filesystem`，等同于`--storage local`）无需Docker和S3，字节存储在`--storage-root`指定的目录下（默认`~/.agent-fs/storage`），每个版本均采用内容寻址，因此`revert`和历史`diff`功能与S3后端完全一致。

just-bash Adapter

just-bash 适配器

Use

@desplega.ai/agent-fs-just-bash

when a

just-bash

environment needs to read and write through agent-fs as its

fs

implementation.

import { Bash } from "just-bash";
import { AgentFsFileSystem } from "@desplega.ai/agent-fs-just-bash";

const fs = new AgentFsFileSystem({
  baseUrl: process.env.AGENT_FS_API_URL,
  apiKey: process.env.AGENT_FS_API_KEY,
  orgId: "org_...",
  driveId: "drive_...",
});

const bash = new Bash({ fs, cwd: "/" });

The adapter uses

/raw

for byte-safe reads/writes and

/ops

for listing and metadata. Empty directories are represented by a hidden

.agent-fs-dir

marker; symlinks are unsupported and throw

EPERM

当

just-bash

环境需要通过agent-fs作为其

fs

实现来读写文件时，使用

@desplega.ai/agent-fs-just-bash

。

import { Bash } from "just-bash";
import { AgentFsFileSystem } from "@desplega.ai/agent-fs-just-bash";

const fs = new AgentFsFileSystem({
  baseUrl: process.env.AGENT_FS_API_URL,
  apiKey: process.env.AGENT_FS_API_KEY,
  orgId: "org_...",
  driveId: "drive_...",
});

const bash = new Bash({ fs, cwd: "/" });

该适配器使用

/raw

进行字节安全读写，使用

/ops

进行文件列表和元数据操作。空目录通过隐藏的

.agent-fs-dir

标记表示；不支持符号链接，会抛出

EPERM

错误。

Essential Patterns

核心使用模式

Use JSON for machine output — pass
```
--json
```
when parsing CLI output (except
```
download
```
without
```
-o
```
, which writes raw bytes to stdout;
```
daemon status
```
and
```
auth register
```
print human-readable text).
Auto-detection — the CLI automatically detects whether the daemon is running. If it is, commands go via HTTP; otherwise, they use embedded mode directly. No user action needed.

Stdin and file upload —

write

accepts raw bytes from stdin or

--file

, and text from

--content

;

append

accepts text via stdin or

--content

bash

# Preferred for multi-line text
echo "content here" | agent-fs write path/to/file.txt

# Inline for short content
agent-fs write path/to/file.txt --content "short text"

# Binary-safe upload
agent-fs write assets/screenshot.png --file ./screenshot.png

Paths — forward-slash separated, no leading slash required. Example:
```
docs/notes/meeting.md
```

Version messages — optional but recommended for auditability:

bash

agent-fs write docs/spec.md --content "..." -m "added API section"

Optimistic concurrency — use

--expected-version

write

to prevent conflicts:

bash

agent-fs write config.json --content '{}' --expected-version 3
# Fails if file is not at version 3

使用JSON作为机器输出 — 解析CLI输出时添加
```
--json
```
参数（除了不带
```
-o
```
的
```
download
```
命令会将原始字节写入标准输出；
```
daemon status
```
和
```
auth register
```
命令输出人类可读文本）。
自动检测 — CLI会自动检测守护进程是否运行。若已运行，命令通过HTTP发送；否则直接使用嵌入式模式。无需用户手动干预。

标准输入与文件上传 —

write

命令接受来自标准输入或

--file

的原始字节，以及来自

--content

的文本；

append

命令接受来自标准输入或

--content

的文本：

bash

# 多行文本推荐方式
echo "content here" | agent-fs write path/to/file.txt

# 短内容可直接内联
agent-fs write path/to/file.txt --content "short text"

# 二进制安全上传
agent-fs write assets/screenshot.png --file ./screenshot.png

路径格式 — 使用斜杠分隔，无需前置斜杠。示例：
```
docs/notes/meeting.md
```

版本信息 — 可选但推荐添加，便于审计：

bash

agent-fs write docs/spec.md --content "..." -m "added API section"

乐观并发控制 — 在

write

命令中使用

--expected-version

参数防止冲突：

bash

agent-fs write config.json --content '{}' --expected-version 3
# 若文件版本不是3则执行失败

Command Quick Reference

命令速查

File Operations

文件操作

Command	Usage	Description
`write`	`agent-fs write <path> [--content <text>] [--file <local-path>] [-m <msg>] [--expected-version <n>]`	Write text or binary bytes
`cat`	`agent-fs cat <path> [--offset <n>] [--limit <n>]`	Read text file content
`edit`	`agent-fs edit <path> --old <text> --new <text> [-m <msg>]`	Find-and-replace in file
`append`	`agent-fs append <path> [--content <text>] [-m <msg>]`	Append to file (stdin or --content)
`tail`	`agent-fs tail <path> [--lines <n>]`	Last N lines (default: 20)
`ls`	`agent-fs ls [path]`	List directory contents (defaults to /)
`stat`	`agent-fs stat <path>`	Show file metadata (size, version, timestamps)
`tree`	`agent-fs tree [path] [--depth <n>]`	Recursive directory listing
`glob`	`agent-fs glob <pattern> [path]`	Find files by pattern ( `.md` , `/.md` )
`rm`	`agent-fs rm <path>`	Delete a file
`mv`	`agent-fs mv <from> <to> [-m <msg>]`	Move or rename a file
`cp`	`agent-fs cp <from> <to>`	Copy a file
`signed-url`	`agent-fs signed-url <path> [--expires-in <seconds>]`	Generate a download URL. On S3/MinIO: a presigned URL (default 24h, max 7 days, `kind: "presigned"` ). On local-FS: an authenticated in-app link ( `kind: "app"` , requires sign-in, non-expiring).
`download`	`agent-fs download <path> [-o <local-path>]`	Download raw bytes

命令	使用方式	描述
`write`	`agent-fs write <path> [--content <text>] [--file <local-path>] [-m <msg>] [--expected-version <n>]`	写入文本或二进制字节
`cat`	`agent-fs cat <path> [--offset <n>] [--limit <n>]`	读取文本文件内容
`edit`	`agent-fs edit <path> --old <text> --new <text> [-m <msg>]`	文件内容查找替换
`append`	`agent-fs append <path> [--content <text>] [-m <msg>]`	向文件追加内容（标准输入或--content）
`tail`	`agent-fs tail <path> [--lines <n>]`	查看文件最后N行（默认20行）
`ls`	`agent-fs ls [path]`	列出目录内容（默认根目录）
`stat`	`agent-fs stat <path>`	显示文件元数据（大小、版本、时间戳）
`tree`	`agent-fs tree [path] [--depth <n>]`	递归列出目录结构
`glob`	`agent-fs glob <pattern> [path]`	按模式查找文件（如 `.md` 、 `/.md` ）
`rm`	`agent-fs rm <path>`	删除文件
`mv`	`agent-fs mv <from> <to> [-m <msg>]`	移动或重命名文件
`cp`	`agent-fs cp <from> <to>`	复制文件
`signed-url`	`agent-fs signed-url <path> [--expires-in <seconds>]`	生成下载URL。在S3/MinIO后端：预签名URL（默认24小时，最长7天， `kind: "presigned"` ）。在本地文件系统后端：带认证的应用内链接（ `kind: "app"` ，需登录，永不过期）。
`download`	`agent-fs download <path> [-o <local-path>]`	下载原始字节

Versioning

版本控制

Command	Usage	Description
`log`	`agent-fs log <path> [--limit <n>]`	Show version history
`diff`	`agent-fs diff <path> --v1 <n> --v2 <n>`	Diff between versions
`revert`	`agent-fs revert <path> --version <n>`	Revert to a previous version

log

works on every backend (version metadata is in SQLite).

revert

and historical

diff

(comparing two stored versions) need a full-tier backend — S3/MinIO and local-filesystem both qualify. On a basic-tier backend without object versioning,

revert

and historical

diff

fail cleanly with

UNSUPPORTED_OPERATION

(HTTP 422);

diff

then degrades to the stored summary instead of full content.

命令	使用方式	描述
`log`	`agent-fs log <path> [--limit <n>]`	查看版本历史
`diff`	`agent-fs diff <path> --v1 <n> --v2 <n>`	对比两个版本的差异
`revert`	`agent-fs revert <path> --version <n>`	恢复到指定版本

log

命令在所有后端均可使用（版本元数据存储在SQLite中）。

revert

和历史

diff

（对比两个已存储版本）需要完整层级后端——S3/MinIO和本地文件系统均符合要求。在无对象版本控制的基础层级后端上，

revert

和历史

diff

会返回

UNSUPPORTED_OPERATION

错误（HTTP 422）；此时

diff

会降级为显示存储的摘要而非完整内容差异。

Search & Discovery

搜索与发现

Command	Usage	Description
`grep`	`agent-fs grep <pattern> <path>`	Regex search in file content
`fts`	`agent-fs fts <pattern> [path]`	Full-text search (FTS5) across all files
`search`	`agent-fs search <query> [--limit <n>]`	Hybrid search (semantic + keyword, best for general queries)
`vec-search`	`agent-fs vec-search <query> [--limit <n>]`	Vector-only semantic search using embeddings
`recent`	`agent-fs recent [path] [--since <duration>] [--limit <n>]`	Recent activity (e.g., `--since 24h` )
`reindex`	`agent-fs reindex [path]`	Re-index files with failed/missing embeddings

When to use which:

```
grep
```
— you know the exact pattern and path (regex)
```
fts
```
— keyword search across all files (fast, FTS5-based)
```
search
```
— general-purpose search combining keywords and meaning (recommended default)
```
vec-search
```
— pure semantic search when you want conceptual matches only

命令	使用方式	描述
`grep`	`agent-fs grep <pattern> <path>`	在文件内容中进行正则搜索
`fts`	`agent-fs fts <pattern> [path]`	对所有文件进行全文搜索（基于FTS5）
`search`	`agent-fs search <query> [--limit <n>]`	混合搜索（语义+关键词，适用于通用查询）
`vec-search`	`agent-fs vec-search <query> [--limit <n>]`	纯向量语义搜索（使用嵌入模型）
`recent`	`agent-fs recent [path] [--since <duration>] [--limit <n>]`	查看近期活动（如 `--since 24h` ）
`reindex`	`agent-fs reindex [path]`	重新索引嵌入失败或缺失的文件

各搜索方式适用场景：

```
grep
```
— 知道精确匹配模式和文件路径时使用（正则表达式）
```
fts
```
— 对所有文件进行关键词搜索（快速，基于FTS5）
```
search
```
— 通用搜索，结合关键词和语义理解（推荐默认使用）
```
vec-search
```
— 纯语义搜索，仅匹配概念相关内容

SQL Queries (DuckDB)

SQL查询（DuckDB）

Command	Usage	Description
`sql`	`agent-fs sql <query> [-t name=path[:format]]... [--max-rows <n>]`	Run DuckDB SQL over stored documents

Supported formats: csv, tsv, parquet, xlsx, json, ndjson/jsonl (each also

.gz

except parquet/xlsx), sqlite (

.db

.sqlite

.sqlite3

), and

.duckdb

. Reference file-format documents directly by quoted drive path inside the query, or bind any document to a table name with

-t

. SQLite/DuckDB databases require a

-t

binding and expose their tables as

<name>.<table>

. Append

:format

to a binding to query documents with non-standard extensions (e.g.

-t logs=/raw/data.txt:csv

). Queries are sandboxed — no host filesystem or network access. Results cap at

--max-rows

(default 1000, max 10000);

truncated: true

in JSON output signals more rows exist.

命令	使用方式	描述
`sql`	`agent-fs sql <query> [-t name=path[:format]]... [--max-rows <n>]`	对存储的文档运行DuckDB SQL查询

支持的格式：csv、tsv、parquet、xlsx、json、ndjson/jsonl（除parquet/xlsx外均支持

.gz

压缩）、sqlite（

.db

.sqlite

.sqlite3

）以及

.duckdb

。可在查询中通过带引号的驱动器路径直接引用指定格式的文档，或使用

-t

参数将任意文档绑定到表名。SQLite/DuckDB数据库需要使用

-t

参数绑定，其表会以

<name>.<table>

形式暴露。在绑定参数后追加

:format

可查询非标准扩展名的文档（如

-t logs=/raw/data.txt:csv

）。查询处于沙箱环境中——无法访问主机文件系统或网络。结果行数上限为

--max-rows

（默认1000，最大10000）；若JSON输出中包含

truncated: true

则表示存在更多结果行。

Comments

评论功能

Command	Usage	Description
`comment add`	`agent-fs comment add <path> --body <text> [--line-start <n>] [--line-end <n>]`	Add a comment to a file
`comment reply`	`agent-fs comment reply <comment-id> --body <text>`	Reply to a comment
`comment list`	`agent-fs comment list [path]`	List comments (with inline replies)
`comment get`	`agent-fs comment get <id>`	Get a comment with its replies
`comment update`	`agent-fs comment update <id> --body <text>`	Update a comment (author only)
`comment delete`	`agent-fs comment delete <id>`	Soft-delete a comment (author only)
`comment resolve`	`agent-fs comment resolve <id>`	Resolve a comment
`comment notifications`	`agent-fs comment notifications [--unread] [--limit <n>]`	List comment notifications for the current user in the active drive
`comment read`	`agent-fs comment read [ids...] [--all]`	Mark selected notification event IDs, or all active-drive notifications, as read

命令	使用方式	描述
`comment add`	`agent-fs comment add <path> --body <text> [--line-start <n>] [--line-end <n>]`	为文件添加评论
`comment reply`	`agent-fs comment reply <comment-id> --body <text>`	回复评论
`comment list`	`agent-fs comment list [path]`	列出评论（包含嵌套回复）
`comment get`	`agent-fs comment get <id>`	获取单条评论及其回复
`comment update`	`agent-fs comment update <id> --body <text>`	更新评论（仅作者可操作）
`comment delete`	`agent-fs comment delete <id>`	软删除评论（仅作者可操作）
`comment resolve`	`agent-fs comment resolve <id>`	标记评论为已解决
`comment notifications`	`agent-fs comment notifications [--unread] [--limit <n>]`	列出当前用户在活动驱动器中的评论通知
`comment read`	`agent-fs comment read [ids...] [--all]`	将指定通知事件ID或活动驱动器中的所有通知标记为已读

Setup & Auth

配置与认证

Command	Usage	Description
`onboard`	`agent-fs onboard [--local] [--filesystem] [--storage <minio\|local>] [--storage-root <dir>] [-y] [--embeddings <provider>]`	Set up agent-fs (storage backend + database + user). `--filesystem` (or `--storage local` ) uses an on-disk backend — no Docker/S3; `--storage-root <dir>` sets its directory.
`init`	`agent-fs init [--local] [-y]`	Alias for `onboard`
`auth register`	`agent-fs auth register <email>`	Register a new user
`auth whoami`	`agent-fs auth whoami`	Show current user info

命令	使用方式	描述
`onboard`	`agent-fs onboard [--local] [--filesystem] [--storage <minio\|local>] [--storage-root <dir>] [-y] [--embeddings <provider>]`	配置agent-fs（存储后端+数据库+用户）。 `--filesystem` （或 `--storage local` ）使用磁盘后端——无需Docker/S3； `--storage-root <dir>` 设置存储目录。
`init`	`agent-fs init [--local] [-y]`	`onboard` 命令的别名
`auth register`	`agent-fs auth register <email>`	注册新用户
`auth whoami`	`agent-fs auth whoami`	显示当前用户信息

Member Management

成员管理

Command	Usage	Description
`member list`	`agent-fs member list`	List org members (use `--drive <id>` for drive members)
`member invite`	`agent-fs member invite <email> --role <role>`	Invite user to org (viewer/editor/admin)
`member update-role`	`agent-fs member update-role <email> --role <role>`	Update org role (use `--drive <id>` for drive role)
`member remove`	`agent-fs member remove <email>`	Remove from org (use `--drive <id>` for drive only)

The

--drive

flag is a global option — place it before the subcommand:

agent-fs --drive <id> member list

Member commands are admin-gated: org-scoped commands require org

admin

; drive-scoped commands (

--drive <id>

) require drive

admin

or admin of the owning org, and the drive must belong to the current org. Non-admins get a permission error; org/drive IDs outside your memberships return "not found".

命令	使用方式	描述
`member list`	`agent-fs member list`	列出组织成员（使用 `--drive <id>` 可列出驱动器成员）
`member invite`	`agent-fs member invite <email> --role <role>`	邀请用户加入组织（角色：viewer/editor/admin）
`member update-role`	`agent-fs member update-role <email> --role <role>`	更新组织用户角色（使用 `--drive <id>` 可更新驱动器角色）
`member remove`	`agent-fs member remove <email>`	将用户从组织移除（使用 `--drive <id>` 仅从指定驱动器移除）

--drive

是全局参数——需放在子命令之前：

agent-fs --drive <id> member list

。

成员管理命令需管理员权限：组织级命令需要组织

admin

角色；驱动器级命令（

--drive <id>

）需要驱动器

admin

角色或所属组织的管理员权限，且驱动器必须属于当前组织。非管理员用户会收到权限错误；不属于当前用户成员关系的组织/驱动器ID会返回「未找到」。

Drive Management

驱动器管理

Command	Usage	Description
`drive list`	`agent-fs drive list`	List drives in current org
`drive create`	`agent-fs drive create <name>`	Create a new drive (requires org admin)
`drive current`	`agent-fs drive current`	Show current drive context
`drive invite`	`agent-fs drive invite <email> --role <role>`	Invite user (viewer/editor/admin)

Drive membership is explicit:

drive list

shows only drives you're a member of. Creating a drive automatically grants you admin membership on it; other users must be invited per drive (or via org invite, which grants access to the default drive).

命令	使用方式	描述
`drive list`	`agent-fs drive list`	列出当前组织中用户所属的驱动器
`drive create`	`agent-fs drive create <name>`	创建新驱动器（需组织管理员权限）
`drive current`	`agent-fs drive current`	显示当前驱动器上下文
`drive invite`	`agent-fs drive invite <email> --role <role>`	邀请用户加入驱动器（角色：viewer/editor/admin）

驱动器成员关系为显式设置：

drive list

仅显示用户所属的驱动器。创建驱动器会自动为创建者赋予管理员权限；其他用户需通过驱动器邀请（或组织邀请，组织邀请会授予默认驱动器访问权限）加入。

Config & Daemon

配置与守护进程

Command	Usage	Description
`config get`	`agent-fs config get <key>`	Get config value (dot notation: `s3.bucket` )
`config set`	`agent-fs config set <key> <value>`	Set config value
`config list`	`agent-fs config list`	Show all configuration
`config validate`	`agent-fs config validate`	Check S3, database, auth, embeddings health
`daemon start`	`agent-fs daemon start`	Start the background daemon
`daemon stop`	`agent-fs daemon stop`	Stop the daemon
`daemon status`	`agent-fs daemon status`	Check if daemon is running

命令	使用方式	描述
`config get`	`agent-fs config get <key>`	获取配置值（支持点符号： `s3.bucket` ）
`config set`	`agent-fs config set <key> <value>`	设置配置值
`config list`	`agent-fs config list`	显示所有配置项
`config validate`	`agent-fs config validate`	检查S3、数据库、认证、嵌入服务的健康状态
`daemon start`	`agent-fs daemon start`	启动后台守护进程
`daemon stop`	`agent-fs daemon stop`	停止守护进程
`daemon status`	`agent-fs daemon status`	检查守护进程是否运行

FUSE Mount (Linux only)

FUSE挂载（仅Linux）

Expose all org drives as a Linux FUSE filesystem so agents can use plain shell verbs (

cat

grep

mv

rm

) against agent-fs content. Requires

/dev/fuse

and

SYS_ADMIN

cap; not available on macOS or in gVisor-based sandboxes.

Two topologies are supported:

Local mode (default): helper talks to a local daemon over a Unix socket. Daemon must be running and have an S3 backend configured.
Remote mode (
```
--remote
```
): helper talks directly to a remote agent-fs HTTP API. No local daemon required — ideal for sandboxes (sprite, E2B, Hetzner VMs, GitHub Actions runners) that can reach a hosted agent-fs but can't run the full daemon stack.

FUSE writes require the

editor

role or better on the drive — on drives where you're a

viewer

, the mount is read-only for file writes (writes fail with

EACCES

; check

<mount>/.agent-fs/errors.ndjson

for the

PERMISSION_DENIED

record).

Command	Usage	Description
`mount`	`agent-fs mount <path> [--allow-other] [--foreground]`	Mount drives at `<path>` via local daemon (e.g. `/mnt/agent-fs/<drive>/` ).
`mount --remote`	`agent-fs mount <path> --remote [--api-url <url>] [--api-key <key>]`	Mount against a remote agent-fs HTTP API. Reads `apiUrl` / `apiKey` from `~/.agent-fs/config.json` or `AGENT_FS_API_URL` / `AGENT_FS_API_KEY` env if flags omitted. Prefer env over `--api-key` (the latter exposes the key in `ps` ).
`umount`	`agent-fs umount <path>`	Unmount the FUSE mountpoint.
`mount status`	`agent-fs mount status`	Show whether a mount is active and where.

将所有组织驱动器暴露为Linux FUSE文件系统，使Agent可使用普通Shell命令（

cat

、

grep

、

mv

、

rm

）操作agent-fs中的内容。需要

/dev/fuse

设备和

SYS_ADMIN

权限；macOS或基于gVisor的沙箱环境不支持。

支持两种拓扑结构：

本地模式（默认）：辅助进程通过Unix套接字与本地守护进程通信。守护进程必须已运行且配置了S3后端。
远程模式（
```
--remote
```
）：辅助进程直接与远程agent-fs HTTP API通信。无需本地守护进程——非常适合可访问托管agent-fs但无法运行完整守护进程栈的沙箱环境（sprite、E2B、Hetzner虚拟机、GitHub Actions运行器等）。

FUSE写入操作需要驱动器的

editor

或更高角色——若用户仅为驱动器的

viewer

，挂载后的文件系统为只读（写入会返回

EACCES

错误；可查看

<mount>/.agent-fs/errors.ndjson

中的

PERMISSION_DENIED

记录）。

命令	使用方式	描述
`mount`	`agent-fs mount <path> [--allow-other] [--foreground]`	通过本地守护进程将驱动器挂载到 `<path>` （如 `/mnt/agent-fs/<drive>/` ）。
`mount --remote`	`agent-fs mount <path> --remote [--api-url <url>] [--api-key <key>]`	挂载远程agent-fs HTTP API。若未指定参数，会从 `~/.agent-fs/config.json` 或环境变量 `AGENT_FS_API_URL` / `AGENT_FS_API_KEY` 读取 `apiUrl` / `apiKey` 。推荐使用环境变量而非 `--api-key` 参数（后者会在 `ps` 命令中暴露密钥）。
`umount`	`agent-fs umount <path>`	卸载FUSE挂载点。
`mount status`	`agent-fs mount status`	显示挂载是否活跃及挂载位置。

Common Workflows

常见工作流

Store and retrieve a document

存储与检索文档

bash

undefined

bash

undefined

Write a document (multi-line via stdin)

写入文档（通过标准输入传入多行内容）

cat <<'EOF' | agent-fs write reports/q1-summary.md -m "Q1 summary draft"

Q1 Summary

Revenue grew 15% quarter over quarter. EOF

Read it back

读取文档

agent-fs cat reports/q1-summary.md

Check metadata

查看元数据

agent-fs stat reports/q1-summary.md

undefined

agent-fs stat reports/q1-summary.md

undefined

Search across files

文件搜索

bash

undefined

bash

undefined

Regex search within a specific path

在指定路径内进行正则搜索

agent-fs grep "revenue|growth" reports/

Full-text search across all files (FTS5 — fast keyword matching)

对所有文件进行全文搜索（FTS5 — 快速关键词匹配）

agent-fs fts "quarterly revenue"

Hybrid search (combines keyword + semantic matching — recommended default)

混合搜索（结合关键词+语义匹配 — 推荐默认使用）

agent-fs search "financial performance metrics" --limit 5

Vector-only semantic search (conceptual matches only)

纯向量语义搜索（仅匹配概念相关内容）

agent-fs vec-search "financial performance metrics" --limit 5

undefined

agent-fs vec-search "financial performance metrics" --limit 5

undefined

Query data files with SQL

使用SQL查询数据文件

bash

undefined

bash

undefined

Query a CSV directly by path

通过路径直接查询CSV文件

agent-fs sql "SELECT category, sum(amount) AS total FROM '/finance/2026.csv' GROUP BY category" --json

Join documents of different formats

合并不同格式的文档

agent-fs sql "SELECT s.name, t.tag FROM sales s JOIN tags t ON s.id = t.id"
-t sales=/data/sales.csv -t tags=/data/tags.parquet

Query a stored SQLite database (tables exposed as app.<table>)

查询存储的SQLite数据库（表以app.<table>形式暴露）

agent-fs sql "SELECT count(*) FROM app.users" -t app=/backups/app.db

Pipe a query via stdin

通过标准输入传入查询语句

echo "SELECT count(*) FROM '/data/events.ndjson'" | agent-fs sql

undefined

echo "SELECT count(*) FROM '/data/events.ndjson'" | agent-fs sql

undefined

Review and revert changes

查看与恢复更改

bash

undefined

bash

undefined

View version history

查看版本历史

agent-fs log docs/spec.md --limit 10

Compare two versions

对比两个版本的差异

agent-fs diff docs/spec.md --v1 2 --v2 5

Revert to version 2

恢复到版本2

agent-fs revert docs/spec.md --version 2

undefined

agent-fs revert docs/spec.md --version 2

undefined

Comments and collaboration

评论与协作

bash

undefined

bash

undefined

Add a comment to a file

为文件添加评论

agent-fs comment add docs/spec.md --body "Needs more detail on auth"

Reply to a comment

回复评论

agent-fs comment reply <comment-id> --body "Added in v3"

List comments

列出评论

agent-fs comment list docs/spec.md

Check unread notifications (the returned IDs are notification event IDs)

查看未读通知（返回的ID为通知事件ID）

agent-fs comment notifications --unread --limit 20

Mark selected notifications as read

将指定通知标记为已读

agent-fs comment read <notification-id> [<notification-id>...]

Or acknowledge every notification in the active drive

或标记活动驱动器中的所有通知为已读

agent-fs comment read --all

Resolve a comment

标记评论为已解决

agent-fs comment resolve <comment-id>

undefined

agent-fs comment resolve <comment-id>

undefined

Set up a new drive and invite users

创建新驱动器并邀请用户

bash

undefined

bash

undefined

Create a shared drive

创建共享驱动器

agent-fs drive create "team-docs"

Invite a teammate

邀请团队成员

agent-fs drive invite alice@company.com --role editor

Check current drive context

查看当前驱动器上下文

agent-fs drive current

undefined

agent-fs drive current

undefined

Manage members

成员管理

bash

undefined

bash

undefined

List org members

列出组织成员

agent-fs member list

List drive members

列出驱动器成员

agent-fs --drive <driveId> member list

Invite a user

邀请用户

agent-fs member invite alice@company.com --role editor

Change role

更新角色

agent-fs member update-role alice@company.com --role admin

Remove from org (cascades to all drives)

从组织移除用户（会同步从所有驱动器移除）

agent-fs member remove alice@company.com

Remove from a specific drive only (keeps org membership)

仅从指定驱动器移除用户（保留组织成员身份）

agent-fs --drive <driveId> member remove alice@company.com

undefined

agent-fs --drive <driveId> member remove alice@company.com

undefined

Check recent activity

查看近期活动

bash

undefined

bash

undefined

What changed in the last hour?

查看过去1小时内的更改

agent-fs recent --since 1h

Recent changes under a specific path

查看指定路径下过去24小时内的近期更改

agent-fs recent docs/ --since 24h --limit 20

undefined

agent-fs recent docs/ --since 24h --limit 20

undefined

Generate a shareable download link

生成可共享的下载链接

bash

undefined

bash

undefined

Default expiry (24 hours)

默认过期时间（24小时）

agent-fs signed-url docs/report.pdf

Custom expiry (1 hour)

自定义过期时间（1小时）

agent-fs signed-url docs/report.pdf --expires-in 3600

JSON output (useful for agents)

JSON输出（适合Agent使用）

agent-fs signed-url docs/report.pdf --json

→ { "url": "https://...", "path": "/docs/report.pdf", "expiresIn": 86400, "expiresAt": "2026-03-20T..." }


On an S3/MinIO backend (`kind: "presigned"`) the URL requires no authentication — anyone with the link can download the file until it expires. Access is RBAC-checked only at generation time (viewer-or-better on the drive); after that the URL is a bearer secret. Don't log it or paste it anywhere you wouldn't paste a credential, and prefer the shortest workable `--expires-in`. Signed URLs serve the correct `Content-Type` header based on file extension (e.g., `application/pdf` for `.pdf`, `image/png` for `.png`), so browsers render them natively.

On a backend without presigned URLs (the local-filesystem backend), `signed-url` does **not** fail — it falls back to an authenticated in-app link (`kind: "app"`, `expiresIn: 0`) of the form `<appUrl>/file/~/<org>/<drive>/<path>`. Unlike a presigned URL this link is **not** a public bearer secret: the daemon's `/raw` route and the web viewer require sign-in, so the recipient must be an authenticated member of the drive. Set `AGENT_FS_APP_URL` (or `appUrl` in config) so the link points at your deployment.

**MIME types on upload:** `write`, `edit`, `append`, and `revert` automatically detect and set the correct `Content-Type` on S3 objects based on file extension. The content type is also stored in the database and visible in `stat` output via the `contentType` field. Raw stdin and `--file` uploads preserve bytes exactly; text search/indexing is applied only when the payload is valid, indexable UTF-8 text.


在S3/MinIO后端（`kind: "presigned"`）生成的URL无需认证——任何人持有链接均可下载文件，直到链接过期。仅在生成URL时会进行RBAC权限检查（需驱动器的viewer或更高角色）；生成后URL即为公开密钥。请勿记录或粘贴到任何可能泄露凭证的地方，建议使用尽可能短的`--expires-in`时间。预签名URL会根据文件扩展名设置正确的`Content-Type`头（如`.pdf`对应`application/pdf`，`.png`对应`image/png`），因此浏览器可直接渲染文件。

在不支持预签名URL的后端（本地文件系统后端），`signed-url`命令不会失败——会回退到带认证的应用内链接（`kind: "app"`，`expiresIn: 0`），格式为`<appUrl>/file/~/<org>/<drive>/<path>`。与预签名URL不同，此链接**不是**公开密钥：守护进程的`/raw`路由和Web查看器需要登录，因此接收者必须是驱动器的已认证成员。设置`AGENT_FS_APP_URL`（或配置中的`appUrl`）可使链接指向你的部署实例。

**上传时的MIME类型：** `write`、`edit`、`append`和`revert`命令会根据文件扩展名自动检测并设置S3对象的正确`Content-Type`。内容类型也会存储在数据库中，可通过`stat`输出的`contentType`字段查看。通过标准输入和`--file`上传的原始字节会被精确保留；仅当内容为有效的可索引UTF-8文本时才会应用文本搜索和索引。

App URL in responses

响应中的应用URL

When

AGENT_FS_APP_URL

is set (e.g.,

https://live.agent-fs.dev

), file-related ops automatically include an

appUrl

field pointing to the file in the live web app:

bash

AGENT_FS_APP_URL=https://live.agent-fs.dev agent-fs stat docs/report.pdf --json

当设置

AGENT_FS_APP_URL

（如

https://live.agent-fs.dev

）时，文件相关操作会自动包含

appUrl

字段，指向Web应用中的文件：

bash

AGENT_FS_APP_URL=https://live.agent-fs.dev agent-fs stat docs/report.pdf --json

→ { ..., "appUrl": "https://live.agent-fs.dev/file/~/org-id/drive-id/docs/report.pdf" }


This applies to any op that returns a `path` or `to` field (write, stat, edit, append, rm, cp, mv, signed-url, etc.).


此规则适用于所有返回`path`或`to`字段的操作（write、stat、edit、append、rm、cp、mv、signed-url等）。

Validate your setup

验证配置

bash

agent-fs config validate

bash

agent-fs config validate

Mount a remote drive from a sandbox

从沙箱挂载远程驱动器

Use

--remote

when the agent is running in a Linux sandbox (sprite, E2B, Hetzner VM, GitHub Actions runner, etc.) that can reach a hosted agent-fs HTTP API but cannot run the full daemon + S3 stack locally.

bash

undefined

当Agent运行在可访问托管agent-fs HTTP API但无法在本地运行完整守护进程+S3栈的Linux沙箱环境（sprite、E2B、Hetzner虚拟机、GitHub Actions运行器等）时，使用

--remote

参数。

bash

undefined

Linux prereqs (run once per sandbox)

Linux前置依赖（每个沙箱运行一次）

sudo apt-get install -y fuse3 sudo chmod 666 /dev/fuse sudo ln -sf /proc/mounts /etc/mtab echo user_allow_other | sudo tee -a /etc/fuse.conf

Auth — either env vars or ~/.agent-fs/config.json

认证 — 使用环境变量或~/.agent-fs/config.json

export AGENT_FS_API_URL=https://agent-fs.example.com export AGENT_FS_API_KEY=<key>

Mount — no local daemon needed

挂载 — 无需本地守护进程

mkdir -p ~/mnt agent-fs mount ~/mnt --remote

Use plain shell verbs against remote content

使用普通Shell命令操作远程内容

ls ~/mnt cat ~/mnt/current/docs/spec.md echo "edit from sandbox $(date)" > ~/mnt/current/notes.txt

Unmount

卸载

fusermount3 -u ~/mnt


See `docs/mounting/` for per-environment guides (sprite, E2B, Hetzner).

fusermount3 -u ~/mnt


更多环境相关指南请查看`docs/mounting/`目录（sprite、E2B、Hetzner）。