Give a project an S3 bucket for files that users upload or download, such as photos or documents. Call it after the first deploy_project, with that project_id; the app restarts with the bucket's variables set (persisted like any env var, so they survive redeploys). The app needs a server (runtime node or python): for each upload the server signs a presigned PUT URL, and for each download a presigned GET URL, with its own key, and the browser sends or fetches the file straight to or from the bucket, never through the app. A static page cannot do this: it has no server to hold the key, and the key must never reach the browser. The app reads S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY (plus S3_PUBLIC_URL for a public bucket) with any S3 SDK. Pass the values to the S3 client explicitly: SDKs read the AWS_* names on their own, not these. Have the app start without these variables and say so until they are set. Private is the default and the right choice for user files. Pass public: true only for files meant for everyone, such as a public gallery's images: they are then readable by anyone at S3_PUBLIC_URL/, outside the project's gate, so a restricted project with a public bucket gets a warning to relay. Idempotent: calling it again returns the same bucket and changes nothing, public included (set_storage_visibility changes that). Refused if the user set any of those S3_* variables themselves. Each plan caps a project's bucket (Free 500 MiB, Pro 50 GiB, Business 100 GiB), measured once a day: past it the app's key can no longer upload (reads, listings, and deletes still work, and nothing is deleted) until the bucket is back under or its plan allows more, and get_project shows storage.read_only with a note to relay. The persistent data directory (SPAWNPOINT_DATA_DIR) needs no call and suits a SQLite file or files only the app reads; a bucket is for files browsers upload or download, or that must outlive the machine. The bucket and every file in it are deleted when the project is terminated.
