CLIO Core

Docs · Context FS

Context FS reference.

The API of Context FS is the mount. This page lists what the daemon implements, what it refuses, how to invoke it, the environment variables that tune it, and the YAML keys of the two modules behind it. The runtime's own command, clio_run, is documented with the Context Runtime.

Daemon
clio_cte_fuse
Modules
clio_cte_filesystem (560.0), clio_cte_stream (565.0)
Page size
1 MiB

Mount semantics

The daemon is a high-level libfuse 3 filesystem. The kernel enforces permission bits (default_permissions) on Linux by default. Writes are sent to the runtime as they happen; a file's size is exact as soon as write() returns on the node that wrote it. fsync and fsyncdir return once the file's pages are on a tier at the configured persistence level and the namespace journal is synced, under the core's default fsync_mode: "durable".

Supported operations

  • Files: create, open, read, write, truncate, fallocate, flush, release, fsync, unlink, rename, link (hard links).
  • Directories: mkdir, rmdir, readdir, fsyncdir.
  • Attributes: getattr, chmod, chown, utimens, statfs.
  • Links: symlink, readlink.
  • Extended attributes: setxattr, getxattr, listxattr, removexattr.

Limits

  • fallocate accepts only the default mode, FALLOC_FL_KEEP_SIZE and FALLOC_FL_ZERO_RANGE. Punch-hole, collapse and insert return EOPNOTSUPP. A negative offset or a length of zero returns EINVAL.
  • rename honours RENAME_NOREPLACE. RENAME_EXCHANGE and RENAME_WHITEOUT return EINVAL.
  • A name longer than the limit returns ENAMETOOLONG from create, mkdir, symlink, link and rename.
  • Not implemented by the daemon: mknod (device nodes, FIFOs), lock and flock, ioctl, copy_file_range, lseek hole-seeking. The kernel's generic behaviour applies for those.
  • With CLIO_FUSE_XATTR=0 every xattr call returns ENOSYS, which the kernel latches for the mount.
  • On macOS the xattr position argument must be 0; anything else returns EINVAL.
  • atime follows relatime by default. -o noatime, -o strictatime and -o relatime are understood by the daemon and removed before libfuse sees them.
  • Case sensitivity is a property of the volume (case_insensitive below), fixed when it is created.

clio_cte_fuse

usage
clio_cte_fuse <mountpoint> [FUSE options]

The daemon attaches to the runtime, creates or binds the filesystem pool (560.0, clio_cte_filesystem), and serves the mount until it is unmounted. Every argument after the mountpoint goes to the FUSE library.

  • -f: stay in the foreground. -d: trace every request. -s: single-threaded.
  • -o allow_other: let other users open the mount (Linux needs user_allow_other in /etc/fuse.conf).
  • -o noatime, -o relatime, -o strictatime: access-time policy; see CLIO_FUSE_ATIME.
  • -o backend=fskit (macOS 15.4+, macFUSE 5.1+): use FSKit; the mountpoint must be under /Volumes.
  • -o uid=-1,gid=-1 (Windows): files belong to the mounting user, which git's ownership check needs.
  • Windows mountpoints are a drive letter (Z:) or an empty folder whose parent exists.
  • Apptainer --fusemount: when the last argument is /dev/fd/N, the daemon drives the pre-opened FUSE fd and reads the mountpoint from CLIO_CTE_FUSE_MOUNTPOINT. This needs a build against libfuse 3.14 headers and a 3.14 runtime library.

Unmount with fusermount3 -u (Linux), umount (macOS) or by stopping the process (Windows).

Environment variables

The daemon reads these at startup. "Multi-node" means the runtime's hostfile has more than one line, or CLIO_FUSE_MULTINODE=1.

Connecting to the runtime

  • CLIO_WITH_RUNTIME (default 1): 0 attaches to a running runtime. 1 starts a runtime inside the daemon if none is reachable. Use 0.
  • CLIO_WAIT_SERVER (default 600 for the mount): seconds to wait for the runtime to answer. The mount defaults higher than other clients so it outlasts a runtime's recovery after a reboot.
  • CLIO_SERVER_ADDR, CLIO_PORT, CLIO_IPC_MODE, CLIO_SERVER_CONF: shared with every runtime client; see the runtime reference.

Caching and coherence

  • CLIO_FUSE_ATTR_CACHE_S (default 1.0; multi-node 0): kernel attribute-cache lifetime in seconds.
  • CLIO_FUSE_ENTRY_CACHE_S (default: same as the attribute lifetime; multi-node 1.0): kernel name-to-inode cache lifetime.
  • CLIO_FUSE_WRITEBACK (default off): 1 enables kernel writeback caching. Safe only for a single writer that fsyncs.
  • CLIO_FUSE_STATFS_TTL_MS (default 1000): how long a capacity answer serves statfs; 0 asks the store every call.
  • CLIO_FUSE_MULTINODE (default: from the hostfile): 0 or 1 forces single- or multi-node behaviour.

Write path

  • CLIO_FUSE_SIEVE (default on): writes and reads go through the daemon's page buffer straight to the CTE. 0 sends every write and read as a filesystem-module task.
  • CLIO_FUSE_SIEVE_CREATE (default on; single-node only): create returns without a round trip and new files are shipped in batches.
  • CLIO_FUSE_WRITE_INFLIGHT_MB (default 256): bytes of writes in flight per daemon before a write waits for the oldest. 0 removes the window.
  • CLIO_FUSE_DIRECT_WRONLY (default on): a file opened write-only bypasses the kernel page cache. 0 disables.
  • CLIO_FUSE_APPEND (default kernel; multi-node deferred): kernel uses the kernel's cached size, reserve reserves the end at the file's stream home, deferred stages the bytes for the stream home to merge.
  • CLIO_FUSE_ASYNC_FLUSH (default on; single-node): close(2) publishes the file asynchronously. 0 waits.
  • CLIO_FUSE_ASYNC_CLOSE (default on): the handle release is not awaited. 0 waits.
  • CLIO_FUSE_ASYNC_UTIMENS (default off): 1 detaches time-stamp updates on a single node. Reorders against later operations, so rsync -a and cp -a need it off.

Attributes and permissions

  • CLIO_FUSE_PERMISSIONS (default on): 0 stops adding -o default_permissions on Linux. On macOS and Windows the option is not added.
  • CLIO_FUSE_ATIME (default relatime): 0 or noatime never updates access time; strict updates it on every read. Set automatically from the -o atime options.
  • CLIO_FUSE_XATTR (default on): 0 answers every xattr call with ENOSYS, which stops the kernel from sending them.

Diagnostics

  • CLIO_ALLOW_PTRACE=1: let a debugger attach to the daemon on hosts with restricted ptrace scope.
  • CTP_LOG_LEVEL (debug, info, success, warning, error, fatal) and CTP_LOG_OUT (log file path): shared with the runtime.

Compose keys

Both modules are entries of the runtime's compose: list. The four keys every entry has (mod_name, pool_name, pool_query, pool_id) and restart are described in the runtime reference. The filesystem entry must come after the chain it points to, and the stream entry before the filesystem.

clio_cte_filesystem

yaml
  - mod_name: clio_cte_filesystem
    pool_name: clio_cte_filesystem
    pool_query: local
    pool_id: "560.0"
    next_pool_id: "563.0"
    metadata_log_path: "${CLIO_STORAGE_ROOT}/cfs_namespace_log"
    # dir_split_entries: 1024
    # case_insensitive: false
    # stream_pool_id: "565.0"
  • next_pool_id: the CTE pool that stores the tags and blobs. Point it at the chain top (563.0) to use the cache, indexer and replication, or at 512.0 to bypass them.
  • metadata_log_path (default unset): node-local journal of the directory table blocks this node is home for. The container id is appended, and ~ and ${VARS} expand. Unset, directory blocks are stored as CTE blobs.
  • dir_split_entries (default 1024): rows a directory block holds before it splits.
  • case_insensitive (default false): compare names case-insensitively while keeping their spelling. Fixed when the volume is created; a runtime configured the other way refuses the volume.
  • stream_pool_id (default "565.0"): the stream pool that owns file sizes and appends.

clio_cte_stream

yaml
  - mod_name: clio_cte_stream
    pool_name: clio_cte_stream
    pool_query: local
    pool_id: "565.0"
    next_pool_id: "563.0"
    staging_pool_id: "561.0"
    # log_path: "/mnt/nvme/$USER/clio/cte_stream_log"
  • next_pool_id: the data path for page writes, normally the chain top.
  • staging_pool_id (default: next_pool_id): where staged appends are written. The default configuration uses the replication pool so they skip the cache.
  • log_path (default unset): node-local log of the sizes and merge plans of the streams this node homes. Without it file sizes do not survive a stop and start.

The CTE core keys that affect the mount (storage tiers, metadata_log_path, fsync_mode, flush_data_period_ms) are documented on the CTE core module page.

Reading mounted files from the CTE API

A file at /notes/a.txt on the mount is a tag named by that path in the pool the filesystem forwards to. Its bytes are blobs "0", "1", ... of 1 MiB each, and its attributes are the blob ~i. The CTE API reference covers TagQuery, GetBlob and SemanticSearch; the quickstart shows a search over mounted files from Python.