Quickstart
Start with ctxfs running locally, optionally track a folder, and read it through the CLI. See the ctxfs guide for a network deployment.
1. Install
Section titled “1. Install”Install ctxd from PyPI. The package includes the CLI, local tracker, and ctxfs:
pip install ctxdctxd --version2. Start and verify local ctxfs
Section titled “2. Start and verify local ctxfs”ctxd endpoint statusThis 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.
3. Optionally track a folder
Section titled “3. Optionally track a folder”ctxd folders add ~/Documents --name Documentsctxd folders listDo this only when this machine should contribute content. The name Documents
is also its CLI path alias.
4. Start the tracker
Section titled “4. Start the tracker”ctxd tracker startThe tracker runs separately from ctxfs and keeps the folders you added synchronized.
Verify both processes:
ctxd endpoint statusctxd tracker statusLook 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.
5. Read from ctxfs
Section titled “5. Read from ctxfs”ctxd files tree Documents --depth 2 --limit 100ctxd files read Documents/notes.mdctxd files grep "deployment" --prefix Documents --limit 20Tracked 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.
Next steps
Section titled “Next steps”- Local tracker for upgrades, moves, logs, and removal
- ctxfs for the filesystem model and all seven reads
- ctxfs API for endpoint parameters and authentication