Inspect a local AFS surface

Use this page to inspect a running local AFS surface that you already own. All pasted output below was produced with arc 2.0.0-beta.28 against a local daemon. Your mounts, paths, and children will differ. Do not treat the sample paths as product defaults.

Safety rules for this walkthrough

Rule	Why
Prefer `explain`, `ls`, `stat`, `read`, `search` first	They inspect without inventing structure
Use only paths your instance already exposes	Unknown paths are not a universal demo tree
Redact secrets from `mount list`	Provider URIs can embed tokens
Do not run `write`/`delete`/`exec` until you know the mount's access mode	Mutation is mount- and permission-specific
Do not assume a fresh `mount add` is immediately usable	Verified gap: CLI may report success while ops fail

1. Confirm version and help

arc --version
arc afs --help

2.0.0-beta.28

The help text lists ls, read, write, delete, stat, exec, explain, search, and mount. Full flags: arc afs.

2. Explain concepts, then mounts

arc afs explain

AFS Overview
============

AFS (Agentic File System) is a virtual filesystem that unifies different data sources into a single namespace.

Core Concepts:
- mount: Mount a data source to a virtual path
- path: Virtual path, e.g., /src, /data
- uri: Data source address, e.g., fs://, git://, sqlite://

Data Flow:
  User Path -> AFS -> /{mount} -> Provider -> Actual Data

arc afs explain mount

explain mount lists this instance's mounts. Output is environment-specific. Example shape (paths redacted where sensitive):

Mounts
======

Current mount configuration:

  /dev/ai/hub
  /dev/web - Web Device — Site Host
  /ash - ASH pipeline DSL
  /modules/vault
  /modules/project
  /modules/memory
  …

arc afs mount list

Example (credentials redacted):

/dev/ai/hub -> aignehub://hub.aigne.io
/dev/web -> web-device:// (Web Device — Site Host)
/ash -> ash:// (ASH pipeline DSL)
/modules/vault -> vault://…[redacted]
/modules/project -> fs:///…/project
/modules/memory -> fs:///…/test-mem
/telegram -> telegram://[REDACTED]
…

arc afs mount validate

Configuration is valid

validate checks configuration shape. It does not prove every mount can serve data.

3. List the root namespace

arc afs ls / -l

Sample (truncated; your root entries differ):

├── 📁 blocklet-manager — Local blocklet workspace manager: …
├── 📁 spaces — Local DID Space logical roots
├── 📁 web — Web Device — renders .web/ + pages/ into static HTML. …
├── 📁 registry
├── 📁 modules
├── 📁 .knowledge (afs:system) — Provider capability index
├── 📁 .meta (afs:system) — Root metadata and mount info
└── 📁 .actions (afs:system) — Root-level executable actions

arc afs stat /

PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete

Root ACTIONS advertise root-level actions. A listed action name is not a promise that every mount supports the same verb.

4. Inspect a known mount path

Pick a path that already appears under your root or in mount list. On the verification host, /modules/project was a local fs:// mount.

arc afs ls /modules
arc afs stat /modules/project
arc afs explain /modules/project

PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z

arc afs read /modules/project/package.json --start-line 1 --end-line 12

{
  "name": "afs",
  "description": "Explore and manage AFS file systems",
  "version": "2.0.0-beta.15",
  …
}

5. Read declared capabilities on a path

When a provider exposes them, capabilities live under /.meta/.capabilities relative to the mount (or aggregated views).

arc afs read /modules/project/.meta/.capabilities

Truncated, verified shape for the local fs mount:

{
  "schemaVersion": 1,
  "provider": "fs",
  "description": "Local filesystem provider",
  "operations": {
    "read": true,
    "list": { "supported": true, "features": { "orderBy": true } },
    "write": {
      "supported": true,
      "features": { "ifMatch": true, "treeMerge": true, "treeToggle": true, "treeIncrement": true }
    },
    "delete": { "supported": true, "features": { "where": true } },
    "search": true,
    "exec": true,
    "stat": true,
    "explain": true,
    "batchWrite": true,
    "batchDelete": true
  }
}

Use this declaration—not a guess from path shape—to decide whether search, write, or batch ops are in contract.

6. Search (provider-defined free text)

arc afs search /modules/project RELEASING

Sample hits (truncated):

/modules/project/CLAUDE.md
/modules/project/README.md
/modules/project/RELEASING.md
…

Search quality, coverage, and ranking are provider-defined. See Search and query.

7. Failures to expect

Command	Observed on beta.28	Meaning
`arc afs read /this-path-does-not-exist-xyz`	`ERROR: Path not found: …` (exit `5`)	Missing path
`arc afs ls /modules/project/definitely-missing-xyz`	`ERROR: Path not found: …` (exit `5`)	Missing child under a mount
`arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'`	`ERROR: Collection query is not available on this surface` (exit `5`)	Query not declared / not available here — not a silent list fallback
`arc afs mount add /modules/… fs:///tmp/…` then `ls`/`read`	Mount message prints success; `explain` may show `TYPE unknown`; `ls` empty or error; `read` not found	Do not treat add success as operational readiness without re-checking

8. Optional: mutate only on a known writable mount

If—and only if—you have a writable mount you control (for example a disposable directory already mounted as fs://), you can exercise write/read/delete. Do not invent a universal writable path.

Verified on a pre-mounted writable fs:// path (/modules/memory on the verification host — your path will differ):

arc afs write /modules/memory/afs-doc-recipe.txt --content 'Hello from AFS recipe' --mode create
arc afs read /modules/memory/afs-doc-recipe.txt
arc afs stat /modules/memory/afs-doc-recipe.txt
arc afs delete /modules/memory/afs-doc-recipe.txt

OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
…
delete

After delete, read fails with not-found. Full task form: Recipes.

What this page does not do

It does not start or reconfigure your daemon for you.
It does not claim a single demo tree ships with every install.
It does not treat repository package names as mounted products.
It does not substitute for formal publish or DID Space deployment checks. Local inspection is a different verification surface; see Runtime boundaries.