Object storage

Configure file storage before uploading durable files or adding app replicas. Sim supports local disk, AWS S3, Azure Blob Storage, and Google Cloud Storage (GCS).

How the backend is selected

Set STORAGE_PROVIDER to local, s3, azure, or gcs to select a backend explicitly. When it is unset, Sim infers the backend from the configured environment variables in this order:

1. Azure Blob Storage — used if AZURE_STORAGE_CONTAINER_NAME is set and either (AZURE_ACCOUNT_NAME + AZURE_ACCOUNT_KEY) or AZURE_CONNECTION_STRING is set.
2. AWS S3 — used if S3_BUCKET_NAME and AWS_REGION are set (and Azure is not configured).
3. Google Cloud Storage — used if GCS_BUCKET_NAME is set (and neither Azure nor S3 is configured).
4. Local disk — the fallback when no cloud backend is activated. Azure activates from its main container or credentials; S3 activates from any of its bucket names or S3_ENDPOINT; GCS activates from GCS_BUCKET_NAME. Dedicated Azure container names or GCS bucket names alone do not activate those providers.

If STORAGE_PROVIDER is unset, Sim uses the first backend whose configuration is complete, in that order. An explicit STORAGE_PROVIDER takes precedence and must be valid and complete.

A partially configured backend is skipped, so a fully configured one later in the order still wins. A backend whose values are present but malformed is different: it stops startup immediately, and a later fully configured one does not take over. An activated but incomplete backend does not fall back to local disk: if no other backend is complete, startup fails with File storage is partially or incorrectly configured. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are checked as a pair — set both or neither.

Set up AWS S3

# Set your region once
export AWS_REGION=us-east-1

# The eight purpose-specific buckets. The CORS and IAM steps below reuse this list.
export SIM_BUCKETS="workspace-files knowledge-base execution-files chat-files
                    copilot-files profile-pictures og-images workspace-logos"

# Create buckets (names must be globally unique — prefix with your org)
for name in ${SIM_BUCKETS:?run the export above first}; do
  if [ "$AWS_REGION" = "us-east-1" ]; then
    aws s3api create-bucket --bucket "myorg-sim-$name" --region "$AWS_REGION"
  else
    aws s3api create-bucket \
      --bucket "myorg-sim-$name" \
      --region "$AWS_REGION" \
      --create-bucket-configuration LocationConstraint="$AWS_REGION"
  fi
done

cat > /tmp/cors.json <<'EOF'
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://sim.yourdomain.com"],
      "AllowedMethods": ["GET", "PUT"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
EOF

for name in ${SIM_BUCKETS:?run the export above first}; do
  aws s3api put-bucket-cors --bucket "myorg-sim-$name" --cors-configuration file:///tmp/cors.json
done

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "arn:aws:s3:::myorg-sim-*",
        "arn:aws:s3:::myorg-sim-*/*"
      ]
    }
  ]
}

# Region + credentials
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...          # omit when using an instance/IRSA role
AWS_SECRET_ACCESS_KEY=...          # omit when using an instance/IRSA role

# Buckets (per purpose)
S3_BUCKET_NAME=myorg-sim-workspace-files
S3_KB_BUCKET_NAME=myorg-sim-knowledge-base
S3_EXECUTION_FILES_BUCKET_NAME=myorg-sim-execution-files
S3_CHAT_BUCKET_NAME=myorg-sim-chat-files
S3_COPILOT_BUCKET_NAME=myorg-sim-copilot-files
S3_PROFILE_PICTURES_BUCKET_NAME=myorg-sim-profile-pictures
S3_OG_IMAGES_BUCKET_NAME=myorg-sim-og-images
S3_WORKSPACE_LOGOS_BUCKET_NAME=myorg-sim-workspace-logos

S3 bucket reference

Set up Azure Blob Storage

Create one private container per purpose; Sim does not create them. Authenticate with either a connection string or an account name and key.

# Credentials — provide ONE of these forms
AZURE_ACCOUNT_NAME=mystorageaccount
AZURE_ACCOUNT_KEY=...
# or
AZURE_CONNECTION_STRING='DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net'

# Containers (per purpose)
AZURE_STORAGE_CONTAINER_NAME=workspace-files
AZURE_STORAGE_KB_CONTAINER_NAME=knowledge-base
AZURE_STORAGE_EXECUTION_FILES_CONTAINER_NAME=execution-files
AZURE_STORAGE_CHAT_CONTAINER_NAME=chat-files
AZURE_STORAGE_COPILOT_CONTAINER_NAME=copilot-files
AZURE_STORAGE_PROFILE_PICTURES_CONTAINER_NAME=profile-pictures
AZURE_STORAGE_OG_IMAGES_CONTAINER_NAME=og-images
AZURE_STORAGE_WORKSPACE_LOGOS_CONTAINER_NAME=workspace-logos

Create all eight containers before applying the variables. For example, with account-name/key credentials:

for name in workspace-files knowledge-base execution-files chat-files copilot-files profile-pictures og-images workspace-logos; do
  az storage container create \
    --name "$name" \
    --account-name "$AZURE_ACCOUNT_NAME" \
    --account-key "$AZURE_ACCOUNT_KEY" \
    --public-access off
done

For connection-string credentials, replace the account options with --connection-string "$AZURE_CONNECTION_STRING".

Direct browser uploads require a Blob service CORS rule on the storage account. Allow your exact Sim origin, GET and PUT, the Content-Type header, and the x-ms-* prefix used by signed blob and metadata headers. Small-file uploads also send If-None-Match; the signature itself is create-only, so a signed URL cannot overwrite an existing final object. Multipart completion verifies uploaded parts on the server:

az storage cors add \
  --services b \
  --methods GET PUT OPTIONS \
  --origins https://sim.yourdomain.com \
  --allowed-headers content-type if-none-match 'x-ms-*' \
  --exposed-headers ETag \
  --max-age 3600 \
  --account-name mystorageaccount \
  --account-key '<account-key>'

If you authenticate with a connection string, replace the last two options with --connection-string "$AZURE_CONNECTION_STRING". CORS is configured once for the account's Blob service and applies to all of its containers.

A full Helm example lives at helm/sim/examples/values-azure.yaml.

Set up Google Cloud Storage

export PROJECT_ID=your-project-id
export LOCATION=us-central1

# The eight purpose-specific buckets. The CORS and IAM steps below reuse this list.
export SIM_BUCKETS="workspace-files knowledge-base execution-files chat-files
                    copilot-files profile-pictures og-images workspace-logos"

# Create buckets (names must be globally unique — prefix with your org)
for name in ${SIM_BUCKETS:?run the export above first}; do
  gcloud storage buckets create "gs://myorg-sim-$name" \
    --project "$PROJECT_ID" \
    --location "$LOCATION" \
    --uniform-bucket-level-access
done

cat > /tmp/cors.json <<'EOF'
[
  {
    "origin": ["https://your-sim-domain.com"],
    "method": ["GET", "PUT"],
    "responseHeader": [
      "Content-Type",
      "ETag",
      "x-goog-if-generation-match",
      "x-goog-meta-uploadid",
      "x-goog-meta-originalname",
      "x-goog-meta-uploadedat",
      "x-goog-meta-purpose",
      "x-goog-meta-userid",
      "x-goog-meta-workspaceid",
      "x-goog-meta-knowledgebaseid",
      "x-goog-meta-folderid",
      "x-goog-meta-workflowid",
      "x-goog-meta-executionid"
    ],
    "maxAgeSeconds": 3600
  }
]
EOF

for name in ${SIM_BUCKETS:?run the export above first}; do
  gcloud storage buckets update "gs://myorg-sim-$name" --cors-file=/tmp/cors.json
done

gcloud iam service-accounts create sim-storage --project "$PROJECT_ID"

for name in ${SIM_BUCKETS:?run the export above first}; do
  gcloud storage buckets add-iam-policy-binding "gs://myorg-sim-$name" \
    --member "serviceAccount:sim-storage@$PROJECT_ID.iam.gserviceaccount.com" \
    --role roles/storage.objectAdmin
done

# Credentials — omit both when using Workload Identity / ADC
GCS_PROJECT_ID=your-project-id            # optional; inferred from credentials when unset
GCS_CREDENTIALS_JSON='{"type":"service_account","client_email":"...","private_key":"..."}'

# Buckets (per purpose)
GCS_BUCKET_NAME=myorg-sim-workspace-files
GCS_KB_BUCKET_NAME=myorg-sim-knowledge-base
GCS_EXECUTION_FILES_BUCKET_NAME=myorg-sim-execution-files
GCS_CHAT_BUCKET_NAME=myorg-sim-chat-files
GCS_COPILOT_BUCKET_NAME=myorg-sim-copilot-files
GCS_PROFILE_PICTURES_BUCKET_NAME=myorg-sim-profile-pictures
GCS_OG_IMAGES_BUCKET_NAME=myorg-sim-og-images
GCS_WORKSPACE_LOGOS_BUCKET_NAME=myorg-sim-workspace-logos

GCS bucket reference

A full Helm example (Workload Identity, GKE) lives at helm/sim/examples/values-gcp.yaml.

Set up S3-compatible storage

Sim works with any S3-compatible store by pointing the S3 client at a custom endpoint. Configure it exactly like AWS S3 (buckets, access key, secret), then add S3_ENDPOINT — and S3_FORCE_PATH_STYLE where the provider requires path-style addressing. The examples below cover Cloudflare R2, MinIO, and RustFS. For other providers, including Backblaze B2, verify signed uploads, multipart completion, and lifecycle behavior against that provider's current S3 support.

S3_ENDPOINT is trusted operator configuration. Sim accepts HTTP and private hosts without its outbound-request guard; do not derive it from untrusted input.

AWS_REGION=auto
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
AWS_ACCESS_KEY_ID='<r2-access-key-id>'
AWS_SECRET_ACCESS_KEY='<r2-secret-access-key>'
S3_BUCKET_NAME=myorg-sim-workspace-files
# ...remaining S3_*_BUCKET_NAME vars, one R2 bucket each

AWS_REGION=us-east-1
S3_ENDPOINT=https://minio.example.com   # must be reachable from users' browsers, not app-pods-only
S3_FORCE_PATH_STYLE=true
AWS_ACCESS_KEY_ID='<minio-access-key>'
AWS_SECRET_ACCESS_KEY='<minio-secret-key>'
S3_BUCKET_NAME=myorg-sim-workspace-files
# ...remaining S3_*_BUCKET_NAME vars, one bucket each

AWS_REGION=us-east-1
S3_ENDPOINT=https://rustfs.example.com   # must be reachable from users' browsers
S3_FORCE_PATH_STYLE=true
AWS_ACCESS_KEY_ID='<rustfs-access-key>'
AWS_SECRET_ACCESS_KEY='<rustfs-secret-key>'
S3_BUCKET_NAME=myorg-sim-workspace-files
# ...remaining S3_*_BUCKET_NAME vars, one bucket each

Apply the configuration

docker compose -f docker-compose.prod.yml up -d

app:
  env:
    AWS_REGION: "us-east-1"
    S3_BUCKET_NAME: "myorg-sim-workspace-files"
    S3_KB_BUCKET_NAME: "myorg-sim-knowledge-base"
    S3_EXECUTION_FILES_BUCKET_NAME: "myorg-sim-execution-files"
    # ...remaining buckets

Configure incomplete multipart cleanup

Sim uploads directly to a create-only final object key and keeps upload-session state in PostgreSQL. The /api/cron/cleanup-tasks endpoint claims expired sessions before deleting uploaded objects or aborting provider multipart state. Neither shipped scheduler calls this endpoint. Configure an authenticated operator-owned schedule as shown in Background jobs. Provider lifecycle cleanup is a second layer for multipart state that outlives its database row:

• On AWS S3 and Google Cloud Storage, abort incomplete multipart uploads after two days on every purpose-specific bucket.
• Azure automatically removes uncommitted blocks after seven days.
• For an S3-compatible provider, configure incomplete-multipart cleanup when its lifecycle implementation supports it. Check the provider's documentation because support varies.

The provider window should exceed the 24-hour upload-session lifetime so an in-progress completion can still recover. Do not add an object-expiration rule for final upload keys.

Verify storage

After restarting with the new configuration:

1. Open the app and upload a document to a knowledge base (or set a profile picture).
2. Confirm an object appears in the corresponding bucket/container.
3. Reload the page — the file should still render (downloads stream back through the app at /api/files/serve).

If uploads fail, check the app logs for credential or permission errors (see Troubleshooting).

Related docs

• Background jobs
• Troubleshooting