Garage v2 S3-compatible object storage reference. Auto-loads when working with Garage, S3 storage, bucket management, @aws-sdk/client-s3, presigned URLs, multipart uploads, object storage, PutObjectCommand, GetObjectCommand.
Version: 2.2.0 Docs: https://garagehq.deuxfleurs.fr/documentation/
See reference.md for the full Admin API v2 and S3 compatibility reference.
forcePathStyle: true is required when using the AWS SDK v3 with Garage. Garage uses path-style URLs (host/bucket/key) by default — virtual-hosted-style (bucket.host/key) requires configuring root_domain in garage.toml.
// Required for Garage
new S3Client({
endpoint: "http://garage:3900",
region: "garage",
forcePathStyle: true,
requestChecksumCalculation: "WHEN_REQUIRED",
responseChecksumValidation: "WHEN_REQUIRED",
credentials: { accessKeyId: "...", secretAccessKey: "..." },
})
The requestChecksumCalculation and responseChecksumValidation options are needed because AWS SDK v3 changed defaults — without them, some operations fail against Garage.
Garage does not implement S3 ACLs or bucket policies. All ACL/policy API calls return 501. Instead, Garage uses its own per-access-key-per-bucket permission model managed through the Admin API:
POST /v2/AllowBucketKey
{ "bucketId": "...", "accessKeyId": "...", "permissions": { "read": true, "write": true, "owner": true } }
Only two lifecycle actions are supported:
AbortIncompleteMultipartUpload — auto-clean abandoned uploadsExpiration — auto-delete objects after a periodNo support for: transitions, versioning, intelligent tiering, or any other lifecycle action.
GetBucketVersioning always returns "not enabled." PutBucketVersioning and ListObjectVersions are not implemented.
Only AWS Signature v4 is supported. Signature v2 (deprecated) is not implemented.
CORS can be set via either:
PUT /v2/PutBucketCorsConfiguration?id={bucketId} (with bearer token)PutBucketCors (with S3 credentials)Don't set CORS in both Caddy/reverse proxy and Garage — browsers reject duplicate CORS headers.
Garage exposes two independent APIs on different ports:
Don't confuse them — S3 credentials don't work on the Admin API and vice versa.
Don't use ACL or bucket policy S3 calls — they return 501 Not Implemented. Use the Admin API's AllowBucketKey/DenyBucketKey instead.
Don't use virtual-hosted-style URLs without configuring root_domain — set forcePathStyle: true in the SDK or configure root_domain in garage.toml.
Don't set CORS in both reverse proxy and Garage — browsers reject responses with duplicate CORS headers. Configure CORS in one place only.
Don't assume S3 feature parity — Garage returns 501 for unimplemented features. Check the compatibility table in reference.md before using advanced S3 features.
Don't use tagging, replication, or notification APIs — none are implemented.