ctxfs
ctxfs stores indexed content and metadata and exposes them through a filesystem-shaped tree that agents can inspect with explicit, bounded operations.
Install and start
Section titled “Install and start”ctxfs ships in the ctxd package and is the storage and retrieval service used
by ctxd commands. There is no backend-selection step. When no external
endpoint is configured, a command that needs ctxfs starts the local process:
pip install ctxdctxd endpoint statusThe default data root is ~/.ctxd/ctxfs. The managed server listens through the
Unix socket ~/.ctxd/local/ctxfs.sock;ctxd endpoint status checks that endpoint
and prints its URL and health. An explicitly configured URL or socket is checked
without launching a second server. Do not launch a second server against the same
data root.
Deployment roles
Section titled “Deployment roles”A deployment can separate three roles:
- The server owns indexed content and metadata and exposes REST and MCP.
- A writer runs the tracker and submits selected folders.
- A reader uses
ctxd files, REST, or MCP against the configured endpoint.
The server may start empty and does not need a tracker or local folders. One machine may run all three roles. This release provides a single ctxfs namespace with multiple scoped credentials; it does not claim multi-tenant isolation.
Standalone and network server
Section titled “Standalone and network server”Run a trusted local socket or authenticated loopback listener in the foreground:
ctxd server serve --root /srv/ctxfs --socket /run/user/1000/ctxfs.sockctxd server serve --root /srv/ctxfs --host 127.0.0.1 --port 8765For another machine to connect, direct TLS and explicit network opt-in are required:
ctxd server serve --root /srv/ctxfs --host 0.0.0.0 --port 8443 \ --allow-network --tls-cert /etc/ctxfs/server.crt \ --tls-key /etc/ctxfs/server.key \ --advertised-url https://ctxfs.example.net:8443The certificate must be valid for the hostname clients use. Keep the TLS private
key owner-only (for example, mode 0600). Install a private CA in each client’s
trust store when a public CA is not used. Do not disable
certificate verification or put a bearer token in a URL. Reverse-proxy and
background-service installation are not provided by these commands.
Credentials and clients
Section titled “Credentials and clients”On the server, create separate least-privilege credentials:
ctxd keys --root /srv/ctxfs create --name reader --scope read --scope statusctxd keys --root /srv/ctxfs create --name writer --scope submit --scope status \ --prefix local-files/ROOT_IDctxd keys --root /srv/ctxfs listThe token is shown once. On the writer client, ctxd folders add records each
folder’s generated prefix in ~/.ctxd/config.json (or the file selected by
CTXD_CONFIG_PATH). Give the server administrator the exact prefix; repeat
--prefix when a writer may submit multiple roots. ctxd folders list does not
print generated prefixes. On a reader or writer client:
ctxd login --endpoint https://ctxfs.example.net:8443ctxd endpoint set https://ctxfs.example.net:8443ctxd status --endpoint https://ctxfs.example.net:8443ctxd endpoint statusread permits REST reads plus MCP tool discovery and calls. submit permits
changes only beneath its server-assigned prefix grants. status permits health
checks and MCP initialization and ping; an HTTP MCP reader therefore normally
needs both read and status.admin grants every capability. Unix sockets
use explicit local peer trust; every TCP request requires a bearer credential,
including loopback.
To rotate a credential, run ctxd keys --root /srv/ctxfs rotate KEY_ID.
Rotation revokes the old key immediately and prints the replacement once. On
each client, run ctxd logout --endpoint URL, then ctxd login --endpoint URL
and enter the replacement. Verify it with ctxd status --endpoint URL.ctxd keys --root /srv/ctxfs revoke KEY_ID also takes effect immediately.
Path model
Section titled “Path model”Every tracked folder has a stable root ID:
local-files/<ROOT_ID>/<path-relative-to-the-tracked-folder>For example, if root abc123 tracks ~/Projects/example, then ~/Projects/example/docs/runbook.md appears at:
local-files/abc123/docs/runbook.mdThe CLI resolves folder names configured on that client to these prefixes, so a
writer can use a path such as Example/docs/runbook.md. A separate reader that
does not have that local folder configuration uses the canonical
local-files/<ROOT_ID>/docs/runbook.md path instead.
Read operations
Section titled “Read operations”| Operation | Purpose |
|---|---|
stat | Inspect one path and its metadata |
ls | List one directory |
tree | Walk a subtree to an optional depth |
glob | Match paths with a glob pattern |
read | Read a complete file up to a byte bound |
read_lines | Read an inclusive line range |
grep | Match a regular expression beneath a prefix |
ctxfs deliberately exposes no shell and no arbitrary commands. grep uses
regular-expression matching, not semantic search.
Verify a tracked file
Section titled “Verify a tracked file”ctxd folders listctxd tracker startctxd files tree Example --depth 2 --limit 100ctxd files read Example/docs/runbook.mdSee the ctxfs API reference for every endpoint and parameter.
Bounded results
Section titled “Bounded results”Listing and matching operations accept a limit. Read operations accept byte or line bounds. Responses include completeness information; callers must not treat a truncated response as exhaustive.
Grep also accepts a per-request timeout_seconds from 0.1 to 60 seconds and
defaults to 2 seconds. A resumable incomplete response sets
continuation_required and includes an opaque next_cursor plus a
continuation_hint; repeat the same pattern and prefix with that cursor. Use
tree or glob to choose a narrow prefix before broad grep. After repeated
timeout stops, continue from the cursor with a larger timeout or narrower prefix
rather than restarting. A cursor is rejected if its resume file changed.
File reads also include content identity information. An agent can use it to detect whether a cited file changed between reads.
The running ctxfs service exposes the seven read operations through MCP at
POST /mcp on its configured endpoint. MCP calls use the same in-process read
service as the REST API.
The managed endpoint is a Unix socket, so the simplest MCP client configuration
is the stdio bridge installed by the same ctxd package:
{ "mcpServers": { "ctxfs": { "command": "ctxd-mcp" } }}The bridge resolves the configured ctxfs endpoint and endpoint-scoped credential itself. MCP tools do not accept endpoint, filesystem-root, or user-identity arguments.