Attachments

HamsterBase Tasks supports adding file attachments to tasks and projects. Files are stored in an S3-compatible object storage service that you provide and control — the app never proxies your files through a HamsterBase server.

Please read before using

• Attachments are stored on your S3 service, not on HamsterBase servers. You are responsible for provisioning the bucket, paying its bills, and keeping its credentials safe.
• Attachment bytes are not end-to-end encrypted. The file is uploaded to your bucket as-is. Anyone with read access to that bucket can read the files. Use bucket-level access control accordingly.
• S3 configuration is stored locally on the current device. It is not synced. You need to configure each device that should be able to upload, download, or preview attachments.
• Only attachment metadata (filename, size, MIME type, S3 object key) is synced between your devices. Without S3 credentials a device can still see the attachment list, but cannot fetch the files.

What you need

Any S3-compatible storage works. Common options:

• Amazon S3
• Cloudflare R2
• Backblaze B2 (S3-compatible endpoint)
• MinIO (self-hosted)
• Other S3-compatible services — Tencent COS, Alibaba OSS, Wasabi, Garage, SeaweedFS, …

You need to know, for the bucket you want to use:

Item	Example
Endpoint URL	https://s3.amazonaws.com, https://<account>.r2.cloudflarestorage.com, http://192.168.1.10:9000
Bucket	my-tasks-attachments
Region	us-east-1, auto (R2), …
Access Key ID	From your S3 provider's IAM / API tokens page
Secret Access Key	The matching secret
Key Prefix (optional)	hamsterbase-tasks/ — restrict all objects under one prefix
Force Path Style	Required for MinIO and many self-hosted servers (see below)

The S3 credentials need permissions to put, get, and head objects in the bucket (plus the bucket itself, for the connection test which calls HeadBucket).

Configuration

Attachments are configured per database. If you use more than one database, each database has its own S3 configuration, stored locally on this device.

1. Open Settings.
2. Go to the Attachments tab.
3. The page header shows which database the configuration applies to. Switch databases first if you want to configure a different one.
4. Click Configure (or Edit if a configuration already exists).
5. Fill in the form:
   • Endpoint URL — full URL including scheme. For AWS S3 use https://s3.amazonaws.com; for R2 use the account-scoped endpoint; for MinIO use your server URL.
   • Bucket — the bucket name (must already exist).
   • Region — the region the bucket lives in. For R2 use auto.
   • Access Key ID / Secret Access Key — credentials with put/get/head permissions.
   • Key Prefix (optional) — a prefix applied to every object written by this app. Useful if you share the bucket with other tools. A trailing / is added automatically if you forget it.
   • Force Path Style (switch) — see Force Path Style below.
6. Click Test Connection. The app calls HeadBucket on your bucket; on success you'll see ✓ Connection successful.
7. Click Save.

Force Path Style

By default, S3 clients use virtual-hosted-style URLs: https://<bucket>.<endpoint>/<key>. Some servers can't serve requests that way and need path-style: https://<endpoint>/<bucket>/<key>.

Turn this switch on if you are using:

• MinIO — almost always required
• Self-hosted Garage / SeaweedFS / Ceph RGW — usually required
• Any other S3-compatible server where uploads fail with DNS or certificate errors against <bucket>.<endpoint>

Leave it off for:

• Amazon S3
• Cloudflare R2
• Backblaze B2
• Most managed S3-compatible services

If you're not sure, try without it first. If uploads or the connection test fail with hostname / TLS errors, enable it and try again.

Clearing the configuration

Clicking the trash icon next to a saved configuration removes it from this device. Files already uploaded to your S3 bucket are not deleted. They become inaccessible from the app until you reconfigure S3 with credentials that can reach the same bucket and key prefix. To remove the files themselves, delete them from your S3 service directly.

How files are stored

Every attachment uploaded from HamsterBase Tasks is written to your bucket at a deterministic key:

{keyPrefix}{databaseId}/attachments/{attachmentId}.{ext}

• keyPrefix — the Key Prefix you set in the form, with a trailing / added if missing. Empty if you didn't set one.
• databaseId — the ID of the HamsterBase database the task or project belongs to. Each database has its own folder under the prefix, so one bucket can safely back multiple databases.
• attachmentId — a random, unique identifier generated locally. Filenames are not used as the key, so two files with the same name don't collide and renaming a file in the app doesn't move it in S3.
• ext — the original file extension, lower-cased. Files with no extension store the bare key.

Example. With Key Prefix hamsterbase-tasks/, database ID db_abc123, and a file Q2-report.pdf:

hamsterbase-tasks/db_abc123/attachments/V1StGXR8_Z5jdHi6B-myT.pdf

Thumbnails

For image attachments (except SVG), the app also generates a small JPEG thumbnail locally during upload and writes it next to the original object with a .thumb.jpg suffix:

hamsterbase-tasks/db_abc123/attachments/V1StGXR8_Z5jdHi6B-myT.pdf.thumb.jpg

Thumbnails are best-effort — if generation or upload fails, the original is still saved and the app falls back to showing a generic file icon.

Deletion

Deleting an attachment in the app is a soft delete: the metadata is marked deleted and the file is hidden from the UI, but the object stays in your S3 bucket. To permanently free storage, delete the objects from S3 yourself (a lifecycle rule on the attachments/ prefix is a convenient way to do this).

Uploading and previewing

Once S3 is configured, an Attachments section appears in the detail panel of every task and project.

• Add files by clicking the drop zone or dragging them onto it.
• Up to 3 files upload concurrently per device; the rest queue.
• Switching databases or signing out cancels in-flight uploads for the previous database.
• Image attachments show inline thumbnails and open in a preview overlay.
• Other file types can be downloaded with the download button.

The attachment count for a task or project is shown next to its other tags in list views.

Troubleshooting

Test Connection fails with Access Denied or 403. The credentials don't have s3:HeadBucket on this bucket, or the bucket name / region is wrong. Verify the IAM policy includes the bucket.

Test Connection fails with a DNS or TLS error. The endpoint host can't be reached as <bucket>.<endpoint>. Enable Force Path Style and try again.

Uploads succeed but the preview is broken. Most likely a CORS issue. The app reads files via GetObject from the browser, so the bucket must allow the app's origin. For self-hosted S3, set a permissive CORS policy on the bucket; for R2/S3, add a CORS rule allowing GET, PUT, HEAD from the app origin.

Switched devices and attachments show as inaccessible. S3 configuration is per-device. Re-enter the same S3 credentials in Settings → Attachments on the new device.