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

# Mount an S3 bucket

> Share files across instances, and keep them after an instance is deleted, by mounting your own S3 bucket as a folder.

An instance's disk belongs to that one instance. For files that several instances share, or that should outlive any of them, mount a bucket you own as a folder. Whatever the instance writes there lands in the bucket, and the next instance that mounts it sees the same files.

It works with Amazon S3 and any S3-compatible store, such as Cloudflare R2. A mount needs a [VM instance](https://www.agent37.com/docs/agents-api/vm-instances.md). On a default instance, [copy files instead](#on-a-default-instance).

## Mount a bucket

Create a VM with the bucket's region and keys in [`env`](https://www.agent37.com/docs/agents-api/instance-environment):

```bash theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vm",
    "env": {
      "RCLONE_S3_PROVIDER": "AWS",
      "RCLONE_S3_REGION": "us-east-2",
      "RCLONE_S3_ACCESS_KEY_ID": "AKIA...",
      "RCLONE_S3_SECRET_ACCESS_KEY": "..."
    }
  }'
```

Everything running in the instance can read those keys, so give them access to this bucket alone. For temporary credentials, add `RCLONE_S3_SESSION_TOKEN`. For a store other than Amazon S3, add `RCLONE_S3_ENDPOINT` and set `RCLONE_S3_PROVIDER` to the name [rclone](https://rclone.org/s3/) uses for it.

Then install rclone and mount the bucket with one [exec](https://www.agent37.com/docs/agents-api/exec.md):

```bash theme={null}
curl -X POST https://sandbox.agent37.app/v1/instances/ab12cd34ef/exec \
  -H "X-Agent37-Key: $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "root",
    "command": "apt-get update -qq && apt-get install -y -qq rclone fuse3 && mkdir -p /mnt/bucket && rclone mount :s3:my-bucket /mnt/bucket --daemon --allow-other --vfs-cache-mode writes"
  }'
```

`/mnt/bucket` is now the bucket. Programs read and write it like any folder, as root or as the image's own user, and they can overwrite, rename, and delete files, including formats that are rewritten in place such as DOCX and XLSX.

| To | Do this |
| - | - |
| Mount one folder of the bucket | Put its path after the bucket name: `:s3:my-bucket/chats/123` |
| Mount read-only | Add `--read-only` |
| Mount several folders | Run `rclone mount` once for each, with its own folder and flags |
| Unmount | `fusermount3 -u /mnt/bucket` |

## What to expect

* **Writes reach the bucket a few seconds later.** A file starts uploading about five seconds after the program closes it. Give it time to finish before you unmount, stop, or delete the instance.
* **A mount is slower than the disk.** Every file is a request to the bucket. Keep working files such as a build or `node_modules` on the instance's disk, and use the bucket for what has to be shared or kept.
* **A restart drops the mount.** It stays through sleep and wake. After a `stop`, `restart`, `resize`, or `update`, send the same exec again once the instance is running.

With a [network allow list](https://www.agent37.com/docs/agents-api/instance-network.md), add the bucket's domain, for example `*.amazonaws.com`.

## On a default instance

A default instance cannot mount a filesystem. With the same `env`, copy files between the bucket and the disk through [exec](https://www.agent37.com/docs/agents-api/exec.md) instead:

```bash theme={null}
# Once, with "user": "root"
apt-get update -qq && apt-get install -y -qq rclone

# Bucket to disk, before the work
rclone copy :s3:my-bucket/chats/123 /home/node/work

# Disk to bucket, after it
rclone copy /home/node/work :s3:my-bucket/chats/123
```


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