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

# Fly.io Sprites

> Mount one Archil disk in many Sprites so they share files with each other and with the rest of your stack.

A [Sprite](https://docs.fly.io/sprites) is a persistent Linux VM on Fly.io that pauses when it's idle and wakes on the next request. A Sprite's own disk persists, but it belongs to that one Sprite. Mount an Archil disk in your Sprites and they can all read and write the same files, which your other machines and the Archil SDK can reach too.

Sprites support FUSE, so the disk mounts as a regular directory. Run the mount as a Sprite service, which the Sprite's runtime starts again whenever the Sprite boots.

## Prerequisites

* The [`sprite` CLI](https://docs.fly.io/sprites/cli/installation), signed in with `sprite login`.
* An Archil disk in the [Archil region](https://docs.archil.com/reference/regions.md) of your choice.

Set your Archil API key and region:

```bash theme={null}
export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-east-1
```

Create the disk with the [`disk` CLI](https://docs.archil.com/reference/disk-cli). The output includes the disk ID and a one-time [mount token](https://docs.archil.com/concepts/authorization.md#token-based-disk-authorization), which grants access to this disk only:

```bash theme={null}
npx disk create sprite-data
```

Export both for the steps below:

```bash theme={null}
export ARCHIL_DISK_ID=dsk-...
export ARCHIL_MOUNT_TOKEN=adt_...
```

## Mount the disk in a Sprite

Create a Sprite and install the `archil` client in it:

```bash theme={null}
sprite create archil-one
sprite exec -s archil-one -- sh -c 'curl -fsSL https://archil.com/install | sh'
```

Save this script on your machine as `archil-mount.sh`. It mounts the disk at `/mnt/archil`, gives the `sprite` user ownership of it, and unmounts when the service is stopped:

```sh archil-mount.sh theme={null}
sudo mkdir -p /mnt/archil
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount "$ARCHIL_DISK_ID" /mnt/archil --region "$ARCHIL_REGION" --conditional || exit 1
sudo chown "$(id -u):$(id -g)" /mnt/archil
trap 'mountpoint -q /mnt/archil && sudo archil unmount /mnt/archil; exit 0' TERM INT
sleep infinity &
wait
```

Upload the script and create a service that runs it, passing the disk ID, region, and token in the service's environment:

```bash theme={null}
sprite exec -s archil-one --file archil-mount.sh:/home/sprite/archil-mount.sh -- \
  sprite-env services create archil --cmd sh --args /home/sprite/archil-mount.sh \
  --env "ARCHIL_DISK_ID=$ARCHIL_DISK_ID,ARCHIL_REGION=$ARCHIL_REGION,ARCHIL_MOUNT_TOKEN=$ARCHIL_MOUNT_TOKEN"
```

The command streams the service's first few seconds of output, ending with `Successfully mounted`. Write a file to the disk:

```bash theme={null}
sprite exec -s archil-one -- sh -c 'echo "Hello from $(hostname)" >> /mnt/archil/visits.log && cat /mnt/archil/visits.log'
```

```text theme={null}
Hello from archil-one
```

## Share the disk between Sprites

Create a second Sprite and repeat the same steps:

```bash theme={null}
sprite create archil-two
sprite exec -s archil-two -- sh -c 'curl -fsSL https://archil.com/install | sh'
sprite exec -s archil-two --file archil-mount.sh:/home/sprite/archil-mount.sh -- \
  sprite-env services create archil --cmd sh --args /home/sprite/archil-mount.sh \
  --env "ARCHIL_DISK_ID=$ARCHIL_DISK_ID,ARCHIL_REGION=$ARCHIL_REGION,ARCHIL_MOUNT_TOKEN=$ARCHIL_MOUNT_TOKEN"
sprite exec -s archil-two -- sh -c 'echo "Hello from $(hostname)" >> /mnt/archil/visits.log && cat /mnt/archil/visits.log'
```

Both Sprites have the disk mounted at the same time, and the second one finds the line the first one wrote:

```text theme={null}
Hello from archil-one
Hello from archil-two
```

## How the disk behaves in a Sprite

**The mount uses conditional mode.** With `--conditional`, every Sprite can read and write anywhere on the disk at the same time, and none of them holds a lock that another Sprite has to wait for. See [Sharing disks](https://docs.archil.com/concepts/sharing-disks.md).

**Pauses need no special handling.** When a Sprite pauses warm, the mount is suspended with it and the client reconnects on wake. When a Sprite boots cold, its runtime starts the `archil` service again, which mounts the disk before you use it.

**Stop the service to unmount.** `sprite-env services stop archil` unmounts the disk and keeps it unmounted until you run `sprite-env services start archil`.

## Clean up

Destroy the Sprites and delete the disk once you no longer need them:

```bash theme={null}
sprite destroy -s archil-one --force
sprite destroy -s archil-two --force
npx disk delete "$ARCHIL_DISK_ID"
```

## Next steps

* [TypeScript SDK](https://docs.archil.com/sdks/typescript.md): read, write, and search the disk without mounting it.
* [Sharing disks](https://docs.archil.com/concepts/sharing-disks.md): how conditional mode and checkouts work.
* [`archil` CLI reference](https://docs.archil.com/reference/archil-cli): every `archil mount` option.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.