> ## 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.

# Quick Start

> Create a CloudFS filesystem over the API, mount it with the JuiceFS client inside a Linux container, and read and write files over POSIX.

Get up and running with CloudFS: create a filesystem over the API, then mount it with the JuiceFS client inside a Linux container and use it like any local directory — write files, read them back, run `git`. The whole path below is verified end-to-end against production.

CloudFS is built on [JuiceFS Community Edition](https://github.com/juicedata/juicefs) (see [How CloudFS Works](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works) for the architecture). There is no server process to run: the JuiceFS client on your host talks directly to a per-filesystem metadata database and to Telnyx Cloud Storage. That means you hold two credentials — the `meta_token` (returned on create) and your `TELNYX_API_KEY` — and the client does the rest.

## 1. Create a Filesystem

`POST /v2/storage/cloudfs`. The `Idempotency-Key` header is **required** (a request without it is rejected with `400`), and so is `region` — there is no default. Allowed regions are `us-central-1`, `us-east-1`, and `us-west-1`.

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/storage/cloudfs \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "agent-fs", "region": "us-east-1"}'
```

Replaying the same `Idempotency-Key` returns the same filesystem instead of creating a second one. A `201` response looks like this:

```json theme={null}
{
  "data": {
    "record_type": "cloudfs",
    "id": "0195e0a2-3f4b-4c8d-9a1e-7b62d4c90f13",
    "name": "agent-fs",
    "status": "ready",
    "meta_url": "postgres://fs_9f3c8e2a4b7d01c6:cloudfs_tok_...@us-east-1.telnyxcloudfs.com:5432/fs_9f3c8e2a4b7d01c6?sslmode=require",
    "meta_token": "cloudfs_tok_...",
    "s3_endpoint": "https://us-east-1.telnyxcloudstorage.com",
    "s3_bucket": "cloudfs-fs-9f3c8e2a4b7d01c6",
    "region": "us-east-1",
    "created_at": "2026-07-14T21:42:01.384912Z",
    "updated_at": "2026-07-14T21:42:03.192847Z"
  }
}
```

<Warning>
  **This is the only time you see the token.** `meta_url` (with the token inline as the password) and the standalone `meta_token` are returned **only** on create and on [rotate](/api-reference/cloudfs-filesystems/rotate-the-metadata-token). `GET /v2/storage/cloudfs/{id}` returns `meta_url` **without** the token and no `meta_token` at all — it cannot be read back. Store the token securely now; if you lose it, rotate to get a new one.
</Warning>

You'll use two values from this response to mount:

* `meta_url` — the full connection string, token included. This is the metadata endpoint; the host is always `us-east-1.telnyxcloudfs.com` regardless of the filesystem's region.
* `id` — the filesystem UUID, for later API calls (detail, rename, rotate).

<Warning>
  The response's `s3_bucket` (`cloudfs-fs-<hex>`) is in **your** Telnyx Cloud Storage account, but it holds CloudFS's internal blocks — not your files. Never modify or delete its objects directly; that corrupts the filesystem. Read and write only through the mount below. See [How CloudFS Works](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works#the-data-lane).
</Warning>

## 2. Mount It with JuiceFS

CloudFS **pre-formats** the volume during provisioning — the bucket already contains the JuiceFS volume metadata.

<Warning>
  Do **not** run `juicefs format`. The filesystem is already formatted; running `format` against it fails with `cannot update volume name`. Go straight to `juicefs mount`. (The one exception: if the filesystem's status is `needs_format`, it *does* need a one-time `juicefs format` before mounting — see [Mounting](/docs/edge-compute/cloudfs/mount#formatting-a-needs_format-filesystem).)
</Warning>

Mount inside a Linux container with FUSE — a portable path that runs the same anywhere and needs no FUSE install on the host. (You can also mount natively on any Linux or macOS host that has FUSE/macFUSE installed.) The data lane authenticates to Telnyx Cloud Storage over S3: your `TELNYX_API_KEY` is the **access key**, and the secret key can be **any non-empty placeholder** (Telnyx Storage ignores the SigV4 signature, but JuiceFS's AWS SDK rejects an empty secret). See [Cloud Storage authentication](/docs/cloud-storage/authentication) for why the secret is ignored.

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    # Start a Linux container with FUSE access, passing your API key through.
    docker run --rm -it --privileged --device /dev/fuse \
      -e TELNYX_API_KEY \
      ubuntu:24.04 bash
    ```

    ```bash theme={null}
    # --- inside the container ---

    # Install the JuiceFS Community Edition client
    apt-get update && apt-get install -y curl fuse
    curl -sSL https://d.juicefs.com/install | sh -

    # Point JuiceFS at your S3 credentials:
    export AWS_ACCESS_KEY_ID="$TELNYX_API_KEY"     # S3 access key = your Telnyx API key
    export AWS_SECRET_ACCESS_KEY="cloudfs-unused"  # any NON-EMPTY value; the signature is ignored

    # Mount with the meta_url from step 1 (token inline). --background --log keeps
    # the mount off your terminal; --no-usage-report opts out of JuiceFS telemetry.
    mkdir -p /mnt/agentfs
    juicefs mount --no-usage-report --background --log /tmp/juicefs.log \
      "postgres://fs_9f3c8e2a4b7d01c6:cloudfs_tok_...@us-east-1.telnyxcloudfs.com:5432/fs_9f3c8e2a4b7d01c6?sslmode=require" \
      /mnt/agentfs
    ```
  </Tab>
</Tabs>

Check `/tmp/juicefs.log` for progress. Once mounted, `df -h /mnt/agentfs` shows the volume.

## 3. Smoke-Test Over POSIX

The mount is a normal directory. Write a file, read it back, and initialize a git repo — all standard POSIX, no CloudFS-specific calls.

```bash theme={null}
cd /mnt/agentfs

# Write and read back
echo "hello cloudfs" > hello.txt
cat hello.txt                 # -> hello cloudfs

# git works against the mounted filesystem
git init -q
git -c user.email=agent@example.com -c user.name=agent add hello.txt
git -c user.email=agent@example.com -c user.name=agent commit -q -m "first commit"
git log --oneline             # -> the commit you just made
```

Data written here lands in Telnyx Cloud Storage as 4 MiB block objects under `chunks/…` in the filesystem's bucket, and persists across unmount and remount — remount with the same `meta_url` and your files are still there.

## Next Steps

* [How CloudFS Works](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works) — the metadata and data lanes, the two credentials, and the on-disk layout
* [Mounting](/docs/edge-compute/cloudfs/mount) — the mount recipe in depth, FUSE requirements, and remount
* [API Reference](/api-reference/cloudfs-filesystems/list-cloudfs-filesystems) — the full endpoint surface, including rotate and delete
* [Overview](/docs/edge-compute/cloudfs) — what CloudFS is and when to use it