> ## Documentation Index > Fetch the complete documentation index at: https://docs.basecut.dev/llms.txt > Use this file to discover all available pages before exploring further. # Storage Providers > Configure where snapshots are stored: S3, GCS, or local filesystem Basecut snapshots consist of manifest metadata, schema definitions, warnings (optional), and compressed CSV data files. You can store these artifacts in cloud storage or on your local filesystem. ## AWS S3 (Recommended for Teams) Store snapshots in Amazon S3 for team sharing and self-hosted agent integration. ### Configuration ```yaml theme={null} # basecut.yml output: provider: s3 bucket: my-basecut-snapshots region: us-east-1 # Optional for S3-compatible storage (e.g., Cloudflare R2, MinIO) endpoint: https://.r2.cloudflarestorage.com prefix: team-a # optional: path prefix within bucket ``` ### Authentication **Option 1: AWS CLI credentials** (recommended for development) ```bash theme={null} aws configure # Enter your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY ``` Basecut automatically uses your `~/.aws/credentials` profile. ### S3-Compatible Backends (Cloudflare R2, MinIO, LocalStack) Use `provider: s3` with a custom `endpoint`: ```yaml theme={null} output: provider: s3 bucket: my-r2-bucket region: auto # recommended for Cloudflare R2 endpoint: https://.r2.cloudflarestorage.com prefix: team-a ``` Set credentials using standard AWS environment variables: ```bash theme={null} export AWS_ACCESS_KEY_ID=... export AWS_SECRET_ACCESS_KEY=... ``` **Option 2: Environment variables** ```bash theme={null} export AWS_ACCESS_KEY_ID=your_key_id export AWS_SECRET_ACCESS_KEY=your_secret_key export AWS_SESSION_TOKEN=your_token # if using temporary credentials ``` **Option 3: IAM role** (recommended for CI/CD and agents) No credentials needed—EC2 instances, ECS tasks, or GitHub Actions with OIDC can use IAM roles. ### Required Permissions ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"], "Resource": [ "arn:aws:s3:::my-basecut-snapshots/*", "arn:aws:s3:::my-basecut-snapshots" ] } ] } ``` ### Bucket Organization Cloud object keys are stored under `snapshots/` (optionally prefixed): ``` s3://my-basecut-snapshots/ └── team-a/ # optional prefix └── snapshots/ ├── 8f4f4b0e-fbc7-4f70.../ │ ├── manifest.json │ ├── schema.json │ ├── warnings.json # optional │ └── tables/ │ ├── public.users.csv.gz │ └── public.orders.csv.gz └── 2d3c1a91-3f23-4d83.../ ``` Use `basecut snapshot list` and `basecut snapshot inspect` to work with snapshot names/tags; object keys are internal storage details. *** ## Google Cloud Storage (Recommended for Teams) Store snapshots in Google Cloud Storage buckets. ### Configuration ```yaml theme={null} # basecut.yml output: provider: gcs bucket: my-basecut-snapshots prefix: team-a # optional: path prefix within bucket ``` ### Authentication **Option 1: gcloud CLI** (recommended for development) ```bash theme={null} gcloud auth application-default login ``` Basecut uses Application Default Credentials from `~/.config/gcloud`. **Option 2: Service account key** ```bash theme={null} export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json ``` **Option 3: Workload Identity** (recommended for GKE) No credentials needed—pods with Workload Identity automatically authenticate. ### Required Permissions Grant the service account `Storage Object Admin` on the bucket: ```bash theme={null} gcloud storage buckets add-iam-policy-binding gs://my-basecut-snapshots \ --member=serviceAccount:basecut@project.iam.gserviceaccount.com \ --role=roles/storage.objectAdmin ``` Or use a custom role with: * `storage.objects.create` * `storage.objects.get` * `storage.objects.list` *** ## Local Filesystem Store snapshots on your local machine. Useful for development and air-gapped environments. ### Configuration ```yaml theme={null} # basecut.yml output: provider: local path: /absolute/path/to/snapshots format: directory ``` Relative paths are allowed, but absolute paths are recommended for clarity. ### Directory Structure Local output writes the snapshot artifact directly to your configured `output.path`: ``` /absolute/path/to/snapshots/ ├── manifest.json ├── schema.json ├── warnings.json # optional └── tables/ ├── public.users.csv.gz └── public.orders.csv.gz ``` ### Machine Identification Local snapshots capture machine metadata for safety. When restoring on a different machine, Basecut warns you but allows the operation if you have access to the file path. ### Use Cases * **Development** - Quick iteration without cloud storage setup * **Air-gapped environments** - No internet access required * **Testing** - Snapshots stay on your machine, no cloud costs **Not recommended for teams**: Local snapshots can't be shared without manual file copying. Use S3/GCS for team collaboration. *** ## Choosing a Provider | Provider | Best For | Team Sharing | Agent Support | Cost | | --------- | --------------------------- | ------------ | --------------------------- | -------------------- | | **S3** | Teams, production workflows | ✅ Yes | ✅ Yes | S3 storage + egress | | **GCS** | GCP-native teams | ✅ Yes | ✅ Yes | GCS storage + egress | | **Local** | Development, testing | ❌ No | ❌ No (local execution only) | Free (disk space) | **Recommendation**: Start with local for initial testing, migrate to S3/GCS when collaborating with teams or using self-hosted agents. *** ## Snapshot Naming and Versioning Reference snapshots by name and optional version: ```bash theme={null} # Latest version of a snapshot basecut snapshot restore dev-seed:latest # Specific tag version basecut snapshot restore dev-seed:brave-lion # Implicit latest basecut snapshot restore dev-seed ``` Each `snapshot create` with the same `--name` creates a new tagged version. Previous versions remain accessible. *** ## Next Steps Understand how storage provider affects execution mode Use cloud storage in GitHub Actions Complete output configuration options Debug storage authentication issues