Skip to content

Local tracker

The local tracker watches folders you select and keeps their ctxfs representation current. The tracker and ctxfs server are separate processes. Starting the tracker starts ctxfs only when the effective endpoint is the default managed local socket; an explicitly configured endpoint is checked instead.

  • macOS or Linux
  • Python 3.11 or 3.12 with pip
  • A local folder if this machine will contribute content

Install ctxd from PyPI:

Terminal window
pip install ctxd
ctxd --version

The package includes the CLI, tracker, and ctxfs.

Terminal window
ctxd tracker start
ctxd endpoint status

tracker start starts ctxfs at the default local endpoint and launches the tracker as a detached process for the current user. It checks an explicitly configured endpoint without starting another server. For example, configure and authenticate to a network server before starting:

Terminal window
ctxd login --endpoint https://ctxfs.example.net:8443
ctxd endpoint set https://ctxfs.example.net:8443
ctxd tracker start

The tracker uses a submit credential whose prefix grant covers the submitted ctxfs paths. The tracker does not start automatically when you sign in or restart the machine. Run ctxd tracker start after each reboot.

Terminal window
ctxd folders add ~/Documents --name Documents
ctxd folders add ~/Projects/example --name Example
ctxd folders list

Each folder name becomes a CLI path alias, such as Documents/notes.md. The underlying ctxfs prefix has a generated root ID, but ordinary CLI use does not require it.

The tracker indexes text files that meet all of these conditions:

  • The file is valid UTF-8 text.
  • Its size is at most 5,000,000 bytes.
  • Its filename does not start with ..
  • Its extension is one of: .cfg,.css,.csv,.html,.ini,.json,.log,.md,.py,.rst,.toml,.ts,.tsx,.txt,.yaml, or .yml.

Other files are not added to ctxfs even though their parent folder is registered. In particular, ctxfs does not expose arbitrary binary files, extensionless files, files with unsupported extensions, or files larger than the size limit. The source folder remains authoritative: the tracker reads it and synchronizes changes to ctxfs without modifying the source files.

The tracker polls registered folders every 10 seconds rather than subscribing to operating-system filesystem events. Consequently, a change may take up to one polling interval, plus processing time, to appear in ctxfs.

Terminal window
ctxd tracker status
ctxd endpoint status

A healthy setup reports the effective endpoint, ctxfs healthy: true, and a running tracker.

Remove the old registration and add the new path:

Terminal window
ctxd folders remove Documents
ctxd folders add /new/path/to/folder --name Documents

This creates a new root identity. Preserving a root identity across a move is not currently exposed by the CLI.

Terminal window
ctxd folders remove Documents

This removes the tracked root from ctxd. It does not delete the source folder.

Terminal window
ctxd tracker stop
pip uninstall ctxd

Uninstalling the package does not remove ~/.ctxd. Review and remove that directory separately only if you intend to delete all ctxd-managed local state.

If ctxfs is unreachable or rejects authentication:

Terminal window
ctxd endpoint status
ctxd tracker status

For an HTTP endpoint, confirm ctxd status --endpoint URL, the server certificate trust chain, and that the credential has submit plus the required prefix. Rotation revokes the old key immediately; run ctxd logout --endpoint URL, then ctxd login --endpoint URL and enter the newly printed token.

If a change has not appeared, restart tracking with ctxd tracker stop followed by ctxd tracker start, then check ctxd tracker status.