Skip to content

Quickstart

Start with ctxfs running locally, optionally track a folder, and read it through the CLI. See the ctxfs guide for a network deployment.

Install ctxd from PyPI. The package includes the CLI, local tracker, and ctxfs:

Terminal window
pip install ctxd
ctxd --version
Terminal window
ctxd endpoint status

This starts ctxfs at the default local Unix socket and checks its health. If you configured an endpoint, the command checks that server instead. The default Unix-socket workflow does not require an API key.

Terminal window
ctxd folders add ~/Documents --name Documents
ctxd folders list

Do this only when this machine should contribute content. The name Documents is also its CLI path alias.

Terminal window
ctxd tracker start

The tracker runs separately from ctxfs and keeps the folders you added synchronized.

Verify both processes:

Terminal window
ctxd endpoint status
ctxd tracker status

Look for ctxfs healthy: true and tracker running: True.ctxd tracker status only reports tracker state. With the default endpoint, ctxd endpoint status ensures local ctxfs is running before checking its health.

Terminal window
ctxd files tree Documents --depth 2 --limit 100
ctxd files read Documents/notes.md
ctxd files grep "deployment" --prefix Documents --limit 20

Tracked files are synchronized while the tracker runs. The same commands read from a configured authenticated network endpoint when the client has the same folder alias. A separate reader uses canonical paths such as local-files/<ROOT_ID>/notes.md.

  • Local tracker for upgrades, moves, logs, and removal
  • ctxfs for the filesystem model and all seven reads
  • ctxfs API for endpoint parameters and authentication