Concurrent Access

CloudFS is a shared filesystem: the same filesystem can be mounted by many clients at once — a fleet of agents, a set of containers, several hosts — and they read and write it concurrently. Because the metadata index lives in one consistent store that every client reads and writes directly (rather than each client keeping its own copy and reconciling later), all mounts converge on the same directory tree.

Mount the Same Filesystem on Many Clients

Every client mounts with the same meta_url (token included) and the same TELNYX_API_KEY. There is nothing per-client to set up — a mount holds no server-side state — so you can add or remove clients at any time. Run the mount recipe on each host:

# on every client — same META_URL, same API key, any mountpoint
juicefs mount --no-usage-report --background --log /tmp/juicefs.log "$META_URL" /mnt/shared

Distribute the token to each client however you manage secrets. If you rotate the token, already-mounted clients keep working on their existing connection; only new mounts need the new meta_url.

What One Client Sees of Another’s Writes

CloudFS gives close-to-open consistency, the standard for shared filesystems: when a client writes a file and closes it, other clients see the new contents the next time they open it. Directory operations — create, rename, delete — commit to the metadata store immediately and become visible to other clients within about a second (the lifetime of a client’s kernel metadata cache). With client A and client B both mounted at /mnt/shared:

# on A — write a file and close it
echo "hello from A" > /mnt/shared/from-a.txt

# on B — read it back
cat /mnt/shared/from-a.txt        # -> hello from A
ls  /mnt/shared                   # -> from-a.txt (plus anything other clients wrote)

Concurrent writes to different files are independent: many clients can each write their own files at the same time with no coordination, and every client reads back exactly what another wrote, byte-for-byte.

Coordinating Writers on the Same File

Two clients writing the same file (or the same byte range) at the same time is the one case that needs coordination — as on any shared filesystem, uncoordinated overlapping writes resolve last-writer-wins. Use file locks: CloudFS supports both BSD locks (flock) and POSIX record locks (fcntl), and JuiceFS coordinates them across clients through the shared metadata. A lock held on one host blocks a conflicting lock on another.

# on A — hold an exclusive lock while appending to a shared worklog
flock -x /mnt/shared/worklog.lock -c 'echo "$(date -u) A: built module X" >> /mnt/shared/worklog'

# on B — the same lock; B waits until A releases (here, up to 5s)
flock -x -w 5 /mnt/shared/worklog.lock -c 'echo "$(date -u) B: ran tests" >> /mnt/shared/worklog'

If B can’t acquire the lock within its timeout, flock exits non-zero and B’s command doesn’t run — so a fleet can serialize access to a shared resource (a worklog, a build output directory, a leader-election file) without any external coordinator.

Worked Example: Two Clients, One Filesystem

Two containers, each an independent client, mounting the same filesystem:

# build a JuiceFS-ready image once
docker build -t cfs-client - <<'EOF'
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y curl ca-certificates fuse3 \
 && curl -sSL https://d.juicefs.com/install | sh -
EOF

# start two clients (each needs FUSE)
docker run -d --name client-a --privileged --device /dev/fuse cfs-client sleep infinity
docker run -d --name client-b --privileged --device /dev/fuse cfs-client sleep infinity

# mount the SAME filesystem in each (same META_URL + API key)
for c in client-a client-b; do
  docker exec -e META_URL="$META_URL" \
    -e AWS_ACCESS_KEY_ID="$TELNYX_API_KEY" -e AWS_SECRET_ACCESS_KEY="placeholder" "$c" \
    sh -c 'mkdir -p /mnt/shared && juicefs mount --no-usage-report --background --log /tmp/j.log "$META_URL" /mnt/shared'
done

# A writes, B reads it
docker exec client-a sh -c 'echo "written by A" > /mnt/shared/hello.txt'
docker exec client-b sh -c 'cat /mnt/shared/hello.txt'   # -> written by A

Caveats

Same-file, uncoordinated concurrent writes resolve last-writer-wins on overlapping regions. Use the locks above whenever more than one client may write the same file.
Metadata latency. Every metadata operation — open, create, rename, lock — is a round-trip to us-east-1 (see The Metadata Lane). Coordination-heavy or many-small-file workloads run faster the closer clients mount to us-east-1; bulk data throughput is unaffected.
One credential set per filesystem. All clients share the same meta_token and API key; there is no per-client scoping within a filesystem.

Next Steps

Mounting a Filesystem — the full mount recipe each client runs
How CloudFS Works — why one consistent metadata store makes shared access work
Quick Start — create a filesystem and mount it

​Mount the Same Filesystem on Many Clients

​What One Client Sees of Another’s Writes

​Coordinating Writers on the Same File

​Worked Example: Two Clients, One Filesystem

​Caveats

​Next Steps

Mount the Same Filesystem on Many Clients

What One Client Sees of Another’s Writes

Coordinating Writers on the Same File

Worked Example: Two Clients, One Filesystem

Caveats

Next Steps