Kernlift

Set up file storage and uploads

Users can upload files and download them through time-limited links, stored in your own S3-compatible bucket or R2 binding.

User uploads and AI-generated media are stored in one bucket. The server writes the files, and the browser never uploads to the bucket directly, so the bucket stays private and needs no CORS rule. Storage is configured in the admin console and needs no environment variables.

Before you begin

  • An admin account with config.read and config.write.
  • A bucket, or an app running on Cloudflare Workers with an R2 bucket bound as BUCKET.

Choose the driver by where the app runs:

DriverUse it whenWhat you set up
S3-compatible endpointAny runtime: Node, Docker, Cloudflare Workers.A bucket and an access key.
Native bucket bindingThe app runs on Cloudflare Workers with an R2 bucket bound as BUCKET.The binding only, no keys.

Create the bucket with the storage provider

ProviderChoose it for
Cloudflare R2A Workers bucket binding or R2 over S3
Amazon S3Private AWS bucket with regional signing
MinIOSelf-hosted object storage

Connect the bucket

Create the bucket and an access key

In your provider's console, create a bucket and an API key that can read, write and delete objects in it.

Use the field mapping in your provider’s guide above.

Go to Settings → Storage Config (/admin/config/storage), tick Enable uploads and select S3-compatible endpoint. Then fill in:

  • Connection → Bucket name: the bucket you created.
  • Connection → Region: the signing region in the provider guide. It defaults to us-east-1.
  • Connection → S3 endpoint: the endpoint from the provider guide, without the bucket name.
  • Credentials → Access Key ID and Secret Access Key: the key pair.

On a first setup the S3 option stays greyed out until these fields are saved. Saving still uses it.

Save

Click Save storage config. The page shows Storage configuration saved., and under Storage driver in the Runtime panel, Read access shows sigv4.

Credential fields are empty every time the page loads. Leave a field blank to keep the saved value.

Set limits and a public domain

Limit file size

Under Limits and MIME types, set Max file size bytes. The default is 10485760 (10 MB).

Limit file types

Edit Image MIME types, Video MIME types, Audio MIME types and File MIME types as comma-separated content types. The defaults are image/png, image/jpeg, image/webp, image/gif; video/mp4, video/webm; audio/mpeg, audio/wav, audio/ogg; and application/pdf, text/plain.

Add a public domain (optional)

If a CDN or custom domain already serves the bucket's objects, fill in Connection → CDN or public access domain, for example https://assets.example.com. Each new upload records a public link made of this domain and the object path. The app does not make the bucket public, and earlier files keep the link they were saved with.

Save

Click Save storage config.

Unticking Enable uploads and saving turns uploads off without removing the saved credentials.

Upload over the API

Users upload from /app/assets/upload. Scripts use a session cookie or an API key with Upload files. The endpoint accepts multipart/form-data (a file field) or JSON (a base64 field). Without folderId the file goes to the user's /uploads folder.

curl -X POST https://your-domain.example/api/assets/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./report.pdf" \
  -F "resourceType=file"
# 201 => { "ok": true, "file": { "id": "file_...", "objectKey": "...", "publicUrl": null, ... } }

Each user has three folders: /, /uploads and /generated, where AI output goes. Uploads to any other folder are rejected. Signed download links expire after at most 24 hours.

Before storage is configured

There is no fallback storage. Uploads fail with S3-compatible storage credentials are not configured. (HTTP 503 from /api/assets/upload), signed links cannot be created, and /setup lists Object storage as not ready.

Verify

Check the upload page

Open /app/assets/upload as any signed-in user. The badge next to the title reads R2 ready once a driver is usable (the label is the same for every provider), or Storage not configured.

Upload a file

Pick a Resource type, choose a File that matches its allowed types, and click Upload. The form shows Uploaded and the file name, or the provider's error.

Download it

Open the file from /app/assets and click Generate signed URL. Open the URL under the button in a new tab. The file loads.

Check the admin view

Platform → Assets (/admin/assets) lists the file under its owner, and /setup lists Object storage as ready.

pnpm validate:files checks the wiring for both drivers. pnpm validate:storage-drivers writes, reads and deletes real objects in your bucket.

Troubleshooting

Upload returns "Content type ... is not allowed"

The file's type is not in the list for the resource type you sent. Add it to the matching MIME list on Storage Config, or send the correct resource type.

Upload returns "Folder does not exist"

The folder id is not one of the caller's own folders. Omit folderId on /api/assets/upload to use /uploads.

S3 upload fails with "Storage upload failed (403)"

The error shows the provider's own code and message. Check the access key, secret and bucket name, and that Region matches what the endpoint expects for signing.

Links on your own site only serve files while the binding driver is selected and the BUCKET binding is present. A link issued before switching drivers cannot be served. Generate a new one.

Reference

Next steps