Skip to main content
Before Archil can read or write to your bucket, the bucket needs to grant Archil access. This is a one-time setup per bucket, regardless of how you use the disk afterwards (mount, disk exec, anything else). The Archil console walks you through this when you create a disk in the UI. This page documents what the console is doing, for setting things up by hand or scripting it.

​
Amazon S3

Amazon S3 supports two ways to authorize Archil:
  • Bucket resource policy — recommended. Archil’s IAM role assumes access to your bucket via a resource policy you attach to the bucket. No long-lived credentials change hands.
  • Static IAM credentials — paste an access key and secret key from an IAM user that has read/write access to the bucket. Simpler to set up, but you’re responsible for rotating the credentials.

​
Bucket resource policy

In the AWS S3 console, select your bucket, open the Permissions tab, and edit the Bucket policy. Add the following statement, substituting YOUR-BUCKET-NAME and your disk’s session ID for YOUR-DISK-SESSION-ID (shown in the Archil console, e.g. asi_us-east-1_tl02r28ami6phda70d1pv): 
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowArchilAccess",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789:role/archil-s3.prod.us-east-1"
            },
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR-BUCKET-NAME",
                "arn:aws:s3:::YOUR-BUCKET-NAME/*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalTag/archilSessionId": "YOUR-DISK-SESSION-ID"
                }
            }
        }
    ]
}
The archilSessionId condition scopes the grant to a single Archil disk, so the bucket is only reachable by that one disk — every other disk in your organization is denied. This is the right default if you point one disk at the bucket. The action list above is the minimum Archil needs: s3:ListBucket for bucket existence checks and listings, s3:GetObject for reads, s3:PutObject for writes (including multipart uploads), and s3:DeleteObject for object removal.
Archil doesn’t call AbortMultipartUpload directly, so it’s not required in the policy. However, on rare failure paths a multipart upload can be left incomplete, and the parts continue to incur storage cost until they’re cleaned up. We recommend either adding s3:AbortMultipartUpload to the action list, or attaching an S3 lifecycle rule that aborts incomplete multipart uploads after a few days.
The exact Principal ARN varies by Archil region — the Archil console displays the precise policy to paste, including the right principal for your region.

​
Authorizing every disk in your organization

If you point many disks at the same bucket — for example, one disk per tenant or per workspace — swap the condition to match on archilAccountId instead. That’s your Archil organization ID (shown in the Archil console, e.g. org_3CjfHc6i0vXj24vu0Wpl8twU3nk) and it’s the same for every disk you create: 
"Condition": {
    "StringEquals": {
        "aws:PrincipalTag/archilAccountId": "YOUR-ARCHIL-ACCOUNT-ID"
    }
}
With this condition every current and future disk in your organization can use the bucket without you having to edit the policy again. The trade-off is that any disk in your organization can reach this bucket, so use it when you control all the disks under that organization.

​
Server-side encryption with KMS (SSE-KMS)

If your bucket is encrypted with SSE-S3 (the default AES256 option), nothing extra is needed — the bucket policy above is sufficient. If your bucket is encrypted with SSE-KMS using a customer-managed KMS key, you also need to grant Archil’s IAM role permission to use that key. Open the key in the AWS KMS console (the key’s ARN is shown at the top of its detail page), edit the Key policy, and add the following statement — substituting YOUR-KMS-KEY-ARN: 
{
    "Sid": "AllowArchilToUseKey",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::123456789:role/archil-s3.prod.us-east-1"
    },
    "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey",
        "kms:DescribeKey"
    ],
    "Resource": "YOUR-KMS-KEY-ARN"
}
kms:Decrypt lets Archil read objects, kms:GenerateDataKey lets it write new objects under envelope encryption, and kms:DescribeKey is occasionally used during client setup.
SSE-KMS with the AWS-managed aws/s3 key does not work for cross-account access. AWS-managed keys can’t be shared outside the account that owns them, so a bucket encrypted with aws/s3 is unreachable from Archil’s role. To use SSE-KMS with Archil, the bucket must use a customer-managed KMS key.
Archil never sets ServerSideEncryption headers on its requests, so whatever default encryption you configure on the bucket is what objects land with. You don’t need to tell Archil which key you’re using.

​
Static credentials

If you’d rather not edit the bucket policy, create an IAM user with s3:* permissions on the bucket and pass its access key ID and secret to Archil when you create the disk: 
import * as archil from "disk";

await archil.createDisk({
  name: "my-disk",
  mounts: [{
    type: "s3",
    bucketName: "my-bucket",
    accessKeyId: "AKIA...",
    secretAccessKey: "...",
  }],
});

​
Google Cloud Storage

Google Cloud Storage authorizes Archil through static AWS-compatible HMAC credentials.
  1. Open the Google Cloud Storage console.
  2. Click Settings, then Interoperability.
  3. Under Service account HMAC, click Create a key for another service account.
  4. Grant the Cloud Storage → Storage Object Admin role to the new service account.
  5. Record the Access key and Secret for the new service account HMAC key.
Pass them when you create the disk: 
await archil.createDisk({
  name: "my-disk",
  mounts: [{
    type: "gcs",
    bucketName: "my-bucket",
    accessKeyId: "GOOG1EABCD1234567890",
    secretAccessKey: "1234567890abcdef1234567890ABCD/EF",
  }],
});

​
Cloudflare R2

Cloudflare R2 authorizes Archil through static AWS-compatible credentials.
  1. Open the Cloudflare console.
  2. Browse to R2 and click Manage R2 API Tokens.
  3. Create a new token with Object Read & Write permissions.
  4. Record the Access Key ID, Secret Access Key, and the default endpoint (looks like https://<account>.r2.cloudflarestorage.com).
Pass them when you create the disk: 
await archil.createDisk({
  name: "my-disk",
  mounts: [{
    type: "r2",
    bucketName: "my-bucket",
    accessKeyId: "R2_ACCESS_KEY_ID",
    secretAccessKey: "R2_SECRET_ACCESS_KEY",
    endpoint: "https://<account>.r2.cloudflarestorage.com",
  }],
});

​
Generic S3-compatible storage

Many providers expose S3-compatible APIs and work with Archil out of the box. To configure one:
  1. Get the S3-compatible API endpoint from your provider.
  2. Create or obtain access credentials (Access Key ID and Secret Access Key) with read/write/list/delete permissions on the bucket.
  3. When creating your disk, select Generic S3 Compatible as the data source type and provide the endpoint plus credentials.
Tested with: