Fly.io Sprites

A Sprite 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, signed in with sprite login.
An Archil disk in the Archil region of your choice.

Set your Archil API key and region:

export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-east-1

Create the disk with the disk CLI. The output includes the disk ID and a one-time mount token, which grants access to this disk only:

npx disk create sprite-data

Export both for the steps below:

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:

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:

archil-mount.sh

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:

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:

sprite exec -s archil-one -- sh -c 'echo "Hello from $(hostname)" >> /mnt/archil/visits.log && cat /mnt/archil/visits.log'

Hello from archil-one

Create a second Sprite and repeat the same steps:

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:

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

sprite destroy -s archil-one --force
sprite destroy -s archil-two --force
npx disk delete "$ARCHIL_DISK_ID"

Next steps

TypeScript SDK: read, write, and search the disk without mounting it.
Sharing disks: how conditional mode and checkouts work.
archil CLI reference: every archil mount option.

Agents

Analytics

Training

Apps & databases

Use Archil on other platforms

Fly.io Sprites

Prerequisites

Mount the disk in a Sprite

How the disk behaves in a Sprite

Clean up

Next steps

​Prerequisites

​Mount the disk in a Sprite

​Share the disk between Sprites

​How the disk behaves in a Sprite

​Clean up

​Next steps

Prerequisites

Mount the disk in a Sprite

Share the disk between Sprites

How the disk behaves in a Sprite

Clean up

Next steps