> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Object storage

Object storage gives your app a private bucket for the files it handles (merchant uploads, generated exports, images) without an S3 account or a service-account key to manage. Files you put under `public/` are served on a hostname of their own.

Object storage is a paid runtime add-on, enabled from **Hosting → Add-ons → Storage**.

## Object storage

Enabling storage provisions a **private Google Cloud Storage bucket** for the environment and grants your app's runtime service account access to it. These variables are injected at deploy time:

| Variable | What it holds |
| - | - |
| `STORAGE_BUCKET` | The bucket name |
| `STORAGE_LOCATION` | The bucket's location |
| `STORAGE_PUBLIC_URL` | Where the bucket's `public/` files are served, `https://<app>-assets.the-meridian.app` |

Your app authenticates with **Application Default Credentials** (the identity it already runs as), so there is no JSON key to store, rotate, or leak. Any Google Cloud Storage client library picks the credentials up on its own.

## How storage is billed

Object storage is a monthly add-on, and its price includes your **first 1 GB** of capacity, so you can upload as soon as the bucket is ready.

Need more room? Add capacity from **Hosting → Add-ons → Storage** in whole GB, at a fixed price per GB per month. Your capacity is the included GB plus every GB you add. For example, the add-on plus 4 extra GB gives you 5 GB. An extra GB bought partway through a billing period is prorated to the end of that period, then renews monthly with the add-on. Extra GB are sold only to an app that has the add-on, and removing the add-on ends them on the same date. Keeping the add-on does not keep them: keep them on their own afterwards. The current prices are shown on the Storage screen.

Used space is measured from the bucket about once an hour, so the number on the Storage screen and in [Billing](/billing) can lag behind uploads you just made. When the bucket reaches its capacity, Meridian stops signing new uploads. The files already in the bucket stay where they are, and nothing is charged automatically: you decide when to add more GB.

## Signed uploads

To let a browser or a CLI upload straight into the bucket, ask Meridian for a **signed upload URL**: you pass the object path and content type, and get back a short-lived `PUT` URL plus the URL the file will be readable at. The upload goes directly to storage, so the file never passes through your app, and the credential you hand out expires on its own.

You can generate one from the Storage screen to try it, and from your backend for real uploads.

## Public files

Everything under the bucket's `public/` prefix is served at `STORAGE_PUBLIC_URL`. Upload `public/logo.png` and it is served at `{STORAGE_PUBLIC_URL}/logo.png`. The bucket itself stays private: Meridian's edge reads those files for you, so nothing in the bucket is ever world-readable.

Keep private files outside `public/`. Only that prefix is served, and everything else in the bucket stays reachable only through your app's credentials or a signed URL.

Public files are served with `Cache-Control: public, max-age=3600` unless you set a `Cache-Control` on the object yourself. To cache them at Google's edge, add the [CDN](/cdn). It caches this hostname along with your app's own.

<Note>
  Storage can be enabled once your production environment exists, and the injected variables reach your live revision once the add-on is ready, with no redeploy.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.