> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concurrent Access

> Mount the same CloudFS filesystem from many clients at once and read and write it concurrently — with cross-client visibility (close-to-open) and file locks for coordinating writers.

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](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works) 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](/docs/edge-compute/cloudfs/mount) on each host:

```bash theme={null}
# 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
```

<Note>
  Distribute the token to each client however you manage secrets. If you [rotate the token](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works#the-metadata-token-lifecycle), already-mounted clients keep working on their existing connection; only new mounts need the new `meta_url`.
</Note>

## 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`:

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```bash theme={null}
# 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](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works#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](/docs/edge-compute/cloudfs/mount) — the full mount recipe each client runs
* [How CloudFS Works](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works) — why one consistent metadata store makes shared access work
* [Quick Start](/docs/edge-compute/cloudfs/quickstart) — create a filesystem and mount it